/ Hex Artifact Content
Login

Artifact 4d0c08f8640c586564a7032b259c5f69bf397850:


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 6e  -in (UTC) and an
1090: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
10a0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
10b0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
10c0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
10d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
10e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
10f0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1100: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
1110: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
1120: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1130: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
1140: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
1150: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
1160: 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52  ON        "--VER
1170: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  S--".#define SQL
1180: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1190: 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  ER --VERSION-NUM
11a0: 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 20 53 51  BER--.#define SQ
11b0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
11c0: 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 2d 49 44      "--SOURCE-ID
11d0: 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  --"../*.** CAPI3
11e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
11f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
1200: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  mbers.** KEYWORD
1210: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
1220: 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  on sqlite3_sourc
1230: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
1240: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
1250: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
1260: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
1270: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
1280: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1290: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
12a0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
12b0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
12c0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
12d0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
12e0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
12f0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1300: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
1310: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
1320: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
1330: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
1340: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1350: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1360: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
1370: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1380: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
1390: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
13a0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
13b0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
13c0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
13d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
13e0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
13f0: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
1400: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
1410: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
1420: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
1430: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
1440: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1450: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
1460: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
1470: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
1480: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1490: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
14a0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
14b0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
14c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
14d0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
14e0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
14f0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1500: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1510: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1520: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
1530: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
1540: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
1550: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
1560: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1570: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
1580: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1590: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
15a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
15b0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
15c0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
15d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
15e0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
15f0: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
1600: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
1610: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
1620: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
1630: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
1660: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
1670: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1680: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
1690: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
16a0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
16b0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
16c0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
16d0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
16e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
16f0: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
1700: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
1710: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
1720: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
1730: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1740: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1750: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
1760: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1770: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
1780: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
1790: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
17a0: 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
17b0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
17c0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e  3_version[];.con
17d0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
17e0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
17f0: 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1800: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1810: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
1820: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1830: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  mber(void);../*.
1840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1850: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f  -Time Library Co
1860: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  mpilation Option
1870: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a  s Diagnostics.**
1880: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1890: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
18a0: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  sed() function r
18b0: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a  eturns 0 or 1 .*
18c0: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65  * indicating whe
18d0: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69  ther the specifi
18e0: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65  ed option was de
18f0: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d  fined at .** com
1900: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65  pile time.  ^The
1910: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20   SQLITE_ prefix 
1920: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66  may be omitted f
1930: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69  rom the .** opti
1940: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74  on name passed t
1950: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  o sqlite3_compil
1960: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20  eoption_used(). 
1970: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f  on_get() functio
19a0: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69  n allows iterati
19b0: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c  ng.** over the l
19c0: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74  ist of options t
19d0: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64  hat were defined
19e0: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
19f0: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67   by.** returning
1a00: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c   the N-th compil
1a10: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74  e time option st
1a20: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20  ring.  ^If N is 
1a30: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a  out of range,.**
1a40: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1a50: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74  option_get() ret
1a60: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1a70: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ter.  ^The SQLIT
1a80: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73  E_ .** prefix is
1a90: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e   omitted from an
1aa0: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  y strings return
1ab0: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1ad0: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75  get()..**.** ^Su
1ae0: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69  pport for the di
1af0: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f  agnostic functio
1b00: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ns sqlite3_compi
1b10: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a  leoption_used().
1b20: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b40: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  () may be omitte
1b50: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20  d by specifying 
1b60: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1b70: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1b80: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e  ON_DIAGS] option
1b90: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
1ba0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1bb0: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  : SQL functions 
1bc0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1bd0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e  ption_used()] an
1be0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  d.** [sqlite_com
1bf0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1c00: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69  ] and the [compi
1c10: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d  le_options pragm
1c20: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  a]..*/.#ifndef S
1c30: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
1c40: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 69  LEOPTION_DIAGS.i
1c50: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nt sqlite3_compi
1c60: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
1c70: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
1c80: 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  me);.const char 
1c90: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1ca0: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1cb0: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
1cc0: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
1cd0: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
1ce0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
1cf0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
1d00: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1d10: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
1d20: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
1d30: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
1d40: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1d50: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
1d60: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1d70: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1d80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1d90: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1da0: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1db0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1dc0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1dd0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1de0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1df0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1e00: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1e10: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1e20: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1e30: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1e40: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1e50: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1e60: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1e70: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1e80: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1e90: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1ea0: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1eb0: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1ec0: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1ed0: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1ee0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1ef0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1f00: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1f10: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1f20: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1f30: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1f40: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1f50: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1f60: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1f70: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1f80: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1f90: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1fa0: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1fb0: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1fc0: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1fd0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1fe0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1ff0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
2020: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
2030: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
2040: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
2050: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
2060: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
2070: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
2080: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
2090: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
20a0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
20b0: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
20c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
20d0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
20e0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
20f0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
2100: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
2110: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2120: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
2130: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2140: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
2150: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
2160: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
2170: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2180: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2190: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
21a0: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
21b0: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
21c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
21d0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
21e0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
21f0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2200: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2210: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
2220: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
2230: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
2240: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2250: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2260: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2270: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2280: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2290: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
22a0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
22b0: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
22c0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
22d0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
22e0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
22f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2300: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2310: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
2320: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
2330: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2340: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2350: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2360: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2370: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2380: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2390: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
23a0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
23b0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23c0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
23d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23e0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
23f0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2400: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2410: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2420: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
2430: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
2440: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
2450: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
2460: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
2470: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2480: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2490: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
24a0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
24b0: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
24c0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
24d0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
24e0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
24f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2500: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2510: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
2520: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2530: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
2540: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
2550: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
2560: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
2570: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2580: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2590: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
25a0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
25b0: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
25c0: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
25d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
25f0: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2600: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2610: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
2620: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
2630: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
2640: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
2650: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
2660: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2670: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2680: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2690: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
26a0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
26b0: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
26c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
26d0: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
26e0: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
26f0: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2700: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2710: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
2720: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
2730: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
2740: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
2750: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
2760: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2770: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2780: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2790: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
27a0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
27b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
27c0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
27d0: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
27e0: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
27f0: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2800: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2810: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2820: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
2830: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
2840: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
2850: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
2860: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
2870: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2880: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2890: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
28a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
28b0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
28c0: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
28d0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
28e0: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
28f0: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2900: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2910: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
2920: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2930: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
2940: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
2950: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 23 20  sqlite_int64;.# 
2960: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e  ifdef SQLITE_UIN
2970: 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74 79 70  T64_TYPE.    typ
2980: 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e 54  edef SQLITE_UINT
2990: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
29a0: 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20 20 0a  int64;.# else  .
29b0: 20 20 20 20 74 79 70 65 64 65 66 20 75 6e 73 69      typedef unsi
29c0: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
29d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
29e0: 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a 23 65  nt64;.# endif.#e
29f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2a00: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2a10: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2a20: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2a30: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2a40: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2a50: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2a60: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2a70: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2a80: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2a90: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2aa0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2ab0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
2ac0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
2ad0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
2ae0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
2af0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2b00: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2b10: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2b20: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2b30: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2b40: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2b50: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2b60: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2b70: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2b80: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2b90: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2ba0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2bb0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2bc0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2bd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2be0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2bf0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2c00: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2c10: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2c20: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2c30: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2c40: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2c50: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2c60: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2c70: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2c80: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2c90: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2ca0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2cb0: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2cc0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2cd0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2ce0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2cf0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2d00: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2d10: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2d20: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2d30: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d50: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2d60: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2d70: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2d80: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2d90: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2da0: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2db0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2dc0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2dd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2de0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2df0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2e00: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2e10: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2e20: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2e30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2e40: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2e50: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2e60: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2e70: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2e80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2e90: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2ea0: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2eb0: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2ec0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2ed0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2ee0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2ef0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2f00: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2f10: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2f20: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2f30: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2f40: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2f50: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2f60: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2f70: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2f80: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2f90: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2fa0: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2fb0: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2fc0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2fd0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2fe0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ff0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
3000: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
3010: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
3020: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3030: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
3040: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
3050: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
3060: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
3070: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
3080: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
3090: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
30a0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
30b0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
30c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
30d0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
30e0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
30f0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
3100: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
3110: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3120: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3130: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3140: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3150: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3160: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3170: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3180: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3190: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
31a0: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
31b0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
31c0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
31d0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
31e0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
31f0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
3200: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
3210: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3220: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3230: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3240: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3250: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3260: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3270: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3280: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3290: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
32a0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
32b0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
32c0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
32d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
32e0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
32f0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
3300: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
3310: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3320: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3330: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3340: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3350: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3360: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3370: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3380: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3390: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
33a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
33b0: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
33c0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
33d0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
33e0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
33f0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
3400: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
3410: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3420: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3430: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3440: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3450: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3460: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3470: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3480: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3490: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
34a0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
34b0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
34c0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
34d0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
34e0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
34f0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
3500: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
3510: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3520: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3530: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3540: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3550: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3560: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3570: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3580: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3590: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
35a0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
35b0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
35c0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
35d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
35e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
35f0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
3600: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3610: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3620: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3630: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3640: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3650: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3660: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3670: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3680: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3690: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
36a0: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
36b0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
36c0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
36d0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
36e0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
36f0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
3700: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3710: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3730: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3740: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3750: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3760: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3770: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3780: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3790: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
37a0: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
37b0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
37c0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
37d0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
37e0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
37f0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
3800: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3810: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3820: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3830: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3840: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3850: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3860: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3870: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3880: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3890: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
38a0: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
38b0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
38c0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
38d0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
38e0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
38f0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
3900: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3910: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3920: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3940: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3950: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3960: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3970: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3980: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3990: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
39a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39b0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39c0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
39d0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
39e0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
39f0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
3a00: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3a10: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3a20: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3a30: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3a40: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3a50: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3a60: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3a70: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3a80: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3a90: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3aa0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3ab0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
3ac0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
3ad0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  eter of.** sqlit
3ae0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
3af0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
3b00: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
3b10: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3b20: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3b30: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3b40: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3b50: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3b60: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3b70: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3b80: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3b90: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3ba0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3bb0: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3bc0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3bd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3be0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3bf0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3c00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3c10: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3c20: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3c30: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3c40: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3c50: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3c60: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3c70: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3c80: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3c90: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3ca0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3cb0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3cc0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3cd0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3ce0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3cf0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3d00: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3d10: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3d20: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3d30: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3d40: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3d50: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3d70: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3d80: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3d90: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3da0: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3db0: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3dc0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3dd0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3de0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3df0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e00: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3e10: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3e20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e30: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3e40: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3e50: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e60: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3e70: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3e80: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3e90: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3ea0: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3eb0: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3ec0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3ed0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3ee0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3ef0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3f00: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f10: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3f20: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3f30: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3f40: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3f50: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3f60: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3f70: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3f80: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3f90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3fa0: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3fb0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3fc0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3fd0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3fe0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3ff0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4000: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
4010: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
4020: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
4040: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
4050: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
4060: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
4070: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4080: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
4090: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
40a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
40b0: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
40c0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
40d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
40e0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
40f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4100: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
4110: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4120: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4130: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4140: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4150: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4160: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4170: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4180: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4190: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
41a0: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
41b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
41c0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
41f0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
4200: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
4210: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
4240: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
4250: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
4260: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4270: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4280: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4290: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
42c0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
42d0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
42e0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
4310: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4320: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
4330: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
4340: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4350: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
4360: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4370: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4380: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4390: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
43a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
43b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
43c0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
43d0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
43e0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
43f0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
4400: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
4410: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4420: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
4430: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
4440: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4450: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4460: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4470: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4480: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4490: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
44a0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
44b0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
44c0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
44d0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
44e0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
44f0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4510: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4520: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4530: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4540: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4550: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4560: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4570: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4590: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
45a0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
45b0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
45c0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
45d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
45e0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
45f0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4600: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4620: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4630: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4640: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4650: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4660: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4670: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4680: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
46a0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
46b0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
46c0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
46d0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
46e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
46f0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4700: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4710: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4720: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4730: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4740: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4750: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4760: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4770: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4780: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4790: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
47a0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
47b0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
47c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
47d0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
47e0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
47f0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4800: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4820: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4830: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4840: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4850: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4870: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4880: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4890: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
48a0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
48b0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
48c0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
48d0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
48e0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
48f0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4900: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4910: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4920: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4930: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4940: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4950: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4980: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4990: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
49a0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
49b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
49c0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
49d0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
49e0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
49f0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4a00: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4a10: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4a20: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4a40: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4a50: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4a60: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4a80: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4a90: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4aa0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4ab0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4ad0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4ae0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4af0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4b00: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4b10: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4b20: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4b30: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4b40: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4b50: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4b60: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4b70: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4b80: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ba0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4bb0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4bc0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4bd0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4be0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4bf0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4c00: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4c10: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c30: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4c40: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4c50: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4c60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4c70: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4c80: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4c90: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4ca0: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4cc0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4cd0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ce0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4cf0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4d00: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4d10: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4d20: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4d30: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4d40: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4d50: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4d60: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4d70: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4d80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4d90: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4da0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4db0: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4dc0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4dd0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4de0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4df0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4e00: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4e10: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4e20: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4e30: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4e40: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4e50: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4e60: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4e70: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4e80: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4e90: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4ea0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4eb0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4ec0: 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a  n 3.3.8 [dateof:
4ed0: 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61  3.3.8].** and la
4ee0: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
4ef0: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
4f00: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
4f10: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
4f20: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
4f30: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
4f40: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73  out errors. Thes
4f50: 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  e [extended resu
4f60: 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e  lt codes] are en
4f70: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4f80: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4f90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4fa0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4fb0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4fc0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4fd0: 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c  des()] API.  Or,
4fe0: 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f   the extended co
4ff0: 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f  de for.** the mo
5000: 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20  st recent error 
5010: 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
5020: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
5030: 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
5040: 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  de()]..*/.#defin
5050: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5060: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
5070: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5080: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
50a0: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
50b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
50c0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
50d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
50e0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
50f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5100: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5110: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
5120: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
5130: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
5140: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5150: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
5160: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
5170: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
5180: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5190: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
51a0: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
51b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51d0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
51e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
51f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
5200: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5210: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
5220: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5230: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
5240: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5250: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
5260: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5270: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
5280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5290: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
52a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52b0: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
52c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52d0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
52e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52f0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
5300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5310: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
5320: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5330: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
5340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5350: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
5360: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5370: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
53a0: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
53c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53d0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
53e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53f0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
5400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5410: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
5420: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5430: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5450: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
5460: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5470: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
5480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5490: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
54a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54b0: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
54c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54d0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
54e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54f0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5510: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
5520: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5530: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
5540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5550: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
5560: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5570: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
5580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5590: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
55a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55b0: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
55c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55d0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45  IOERR_DELETE_NOE
55e0: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  NT      (SQLITE_
55f0: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29  IOERR | (23<<8))
5600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5610: 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20  IOERR_MMAP      
5620: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5630: 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29  IOERR | (24<<8))
5640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5650: 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54  IOERR_GETTEMPPAT
5660: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5670: 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29  IOERR | (25<<8))
5680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5690: 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20  IOERR_CONVPATH  
56a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56b0: 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29  IOERR | (26<<8))
56c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56d0: 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20  IOERR_VNODE     
56e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56f0: 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29  IOERR | (27<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 20  IOERR_AUTH      
5720: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5730: 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29  IOERR | (28<<8))
5740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5750: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
5760: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
5770: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
5780: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5790: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
57a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
57b0: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
57c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57d0: 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20  E_BUSY_SNAPSHOT 
57e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57f0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c  E_BUSY   |  (2<<
5800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5810: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45  TE_CANTOPEN_NOTE
5820: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49  MPDIR      (SQLI
5830: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31  TE_CANTOPEN | (1
5840: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5850: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53  LITE_CANTOPEN_IS
5860: 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51  DIR          (SQ
5870: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5880: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5890: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
58a0: 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28  FULLPATH       (
58b0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
58c0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
58d0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
58e0: 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20  N_CONVPATH      
58f0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5900: 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  N | (4<<8)).#def
5910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
5920: 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  PT_VTAB         
5930: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55     (SQLITE_CORRU
5940: 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  PT | (1<<8)).#de
5950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5960: 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20  ONLY_RECOVERY   
5970: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5980: 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23  ONLY | (1<<8)).#
5990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
59a0: 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20  ADONLY_CANTLOCK 
59b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
59c0: 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29  ADONLY | (2<<8))
59d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59e0: 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43  READONLY_ROLLBAC
59f0: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5a00: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38  READONLY | (3<<8
5a10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a20: 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56  E_READONLY_DBMOV
5a30: 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ED        (SQLIT
5a40: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c  E_READONLY | (4<
5a50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a60: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
5a70: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
5a80: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
5a90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5aa0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48  TE_CONSTRAINT_CH
5ab0: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  ECK        (SQLI
5ac0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5ad0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5ae0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5af0: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28  T_COMMITHOOK   (
5b00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b10: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5b20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5b30: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59  RAINT_FOREIGNKEY
5b40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b50: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a  RAINT | (3<<8)).
5b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b70: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49  ONSTRAINT_FUNCTI
5b80: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  ON     (SQLITE_C
5b90: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c  ONSTRAINT | (4<<
5ba0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bb0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f  TE_CONSTRAINT_NO
5bc0: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49  TNULL      (SQLI
5bd0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5be0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5bf0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c00: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28  T_PRIMARYKEY   (
5c10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c20: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  T | (6<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c40: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20  RAINT_TRIGGER   
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c60: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a  RAINT | (7<<8)).
5c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c80: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45  ONSTRAINT_UNIQUE
5c90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5ca0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c  ONSTRAINT | (8<<
5cb0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54  TE_CONSTRAINT_VT
5cd0: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AB         (SQLI
5ce0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5cf0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5d00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d10: 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28  T_ROWID        (
5d20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d30: 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66  T |(10<<8)).#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5d50: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20  E_RECOVER_WAL   
5d60: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43     (SQLITE_NOTIC
5d70: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  E | (1<<8)).#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5d90: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41  E_RECOVER_ROLLBA
5da0: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43  CK (SQLITE_NOTIC
5db0: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  E | (2<<8)).#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
5dd0: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20  NG_AUTOINDEX    
5de0: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49     (SQLITE_WARNI
5df0: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NG | (1<<8)).#de
5e00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
5e10: 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20  _USER           
5e20: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48      (SQLITE_AUTH
5e30: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5e40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41  ne SQLITE_OK_LOA
5e50: 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20  D_PERMANENTLY   
5e60: 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28    (SQLITE_OK | (
5e70: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5e80: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5e90: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5ea0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5eb0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5ec0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5ed0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5ee0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5ef0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5f00: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5f10: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5f20: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5f30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5f40: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5f50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f60: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5f70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5f80: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5f90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5fa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fb0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5fc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5fd0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5fe0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6000: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
6010: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6020: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
6030: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6040: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6050: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
6060: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
6070: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
6080: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6090: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
60a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
60b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60d0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
60e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
60f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6110: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
6120: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
6130: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6140: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6170: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6180: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6190: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
61a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61b0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
61c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
61d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61f0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
6200: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6210: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6220: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6230: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
6240: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6250: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6280: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6290: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62b0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
62c0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
62d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62f0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
6300: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
6310: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6320: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6330: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
6340: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6350: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6370: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6380: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6390: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
63a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
63b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63c0: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
63d0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
63e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
63f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6400: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6410: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
6420: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
6430: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6440: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6450: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6460: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6470: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6480: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6490: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
64a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
64b0: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
64c0: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
64d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
64e0: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
64f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6500: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
6510: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
6520: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
6530: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
6540: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6550: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6560: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6570: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6580: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
6590: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
65a0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
65b0: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
65c0: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
65d0: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
65e0: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
65f0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
6600: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
6610: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
6620: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6630: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
6640: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6650: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6660: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6670: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6680: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6690: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
66a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
66b0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
66c0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
66d0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
66e0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
66f0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
6700: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
6710: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6720: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6730: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6740: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6750: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6760: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6770: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6780: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6790: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
67a0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
67b0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
67c0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
67d0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
67e0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
67f0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
6800: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
6810: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6820: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6830: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
6840: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6850: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6860: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6870: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6880: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6890: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
68a0: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
68b0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
68c0: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
68d0: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
68e0: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
68f0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
6900: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
6910: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
6920: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
6930: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
6940: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6950: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6960: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6970: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6980: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6990: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
69a0: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
69b0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
69c0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
69d0: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
69e0: 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  s that a file ca
69f0: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6a00: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6a10: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6a20: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6a30: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6a40: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6a50: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6a60: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6a70: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
6a80: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
6a90: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
6aa0: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ac0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
6ad0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
6ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6af0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
6b00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b10: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6b20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b30: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6b40: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6b50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b60: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
6b70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b80: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
6b90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
6ba0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6bb0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
6bc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6bd0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
6be0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6bf0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6c10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6c20: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6c30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6c40: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6c50: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c70: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
6c80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c90: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
6ca0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6cb0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
6cc0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
6cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ce0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
6cf0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6d00: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6d10: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6d20: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6d30: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6d40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6d50: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6d60: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6d70: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6d80: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
6d90: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
6da0: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
6db0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6dc0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6dd0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6de0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6df0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6e00: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6e10: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6e20: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6e30: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6e40: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6e50: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6e60: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6e70: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6e80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6e90: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6ea0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6eb0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6ed0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6ee0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6ef0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6f00: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6f10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6f20: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6f30: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6f40: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6f50: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6f60: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6f70: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6f80: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6f90: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6fa0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6fb0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6fc0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6fd0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6fe0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6ff0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
7000: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7010: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
7020: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
7030: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
7040: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
7050: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
7060: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
7070: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
7080: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
7090: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
70a0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
70b0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
70c0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
70d0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
70e0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
70f0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
7100: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
7110: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7120: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
7130: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
7140: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
7150: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
7160: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
7170: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
7180: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
7190: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
71a0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
71b0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
71c0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
71d0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
71e0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
71f0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
7200: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
7210: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
7220: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
7230: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
7240: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
7250: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
7260: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
7270: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
7280: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
7290: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
72a0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
72b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
72c0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
72d0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
72e0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
72f0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
7300: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7310: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7320: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7330: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7340: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7350: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7360: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
7370: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
7380: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
7390: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
73a0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
73b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
73c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
73d0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
73e0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
73f0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
7400: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7410: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7420: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7430: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7440: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7450: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7460: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
7470: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7480: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
7490: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
74a0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
74b0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
74c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
74d0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
74e0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
74f0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
7500: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7510: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7520: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7530: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7540: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7550: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7560: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
7570: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7580: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
7590: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
75a0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
75b0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
75c0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
75d0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
75e0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
75f0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
7600: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7610: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7620: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7630: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7640: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7650: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7660: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
7670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7680: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
7690: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
76a0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
76b0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
76c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
76d0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
76e0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
76f0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
7700: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7710: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7720: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7730: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7740: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7750: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7760: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7770: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
7780: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7790: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
77a0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
77b0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
77c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
77d0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
77e0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
77f0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
7800: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7810: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7820: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7830: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7840: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7850: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7860: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
7870: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
7880: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
7890: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
78a0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
78b0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
78d0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
78e0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
78f0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
7900: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7910: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7920: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7930: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7940: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7950: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7960: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
7970: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
7980: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
7990: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
79a0: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
79b0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
79c0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
79d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
79e0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
79f0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7a00: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7a10: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7a20: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7a30: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7a40: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7a50: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7a60: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
7a70: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
7a80: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
7a90: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
7aa0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
7ab0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
7ac0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
7ad0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
7ae0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
7af0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
7b00: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7b10: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7b20: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7b30: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7b40: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7b50: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7b60: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
7b70: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
7b80: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
7b90: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
7ba0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7bb0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
7bc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
7bd0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
7be0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7bf0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
7c00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7c10: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7c20: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7c30: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7c40: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7c50: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7c60: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
7c70: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7c80: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
7c90: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
7ca0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
7cb0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
7cc0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
7cd0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
7ce0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
7cf0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
7d00: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7d10: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7d20: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7d30: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7d40: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7d50: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7d60: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7d70: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7d80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7d90: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7da0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7db0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7dc0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7dd0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7de0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7df0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7e00: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7e10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7e20: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7e30: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7e40: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7e50: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7e60: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7e70: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7e80: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7e90: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7ea0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7eb0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7ec0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7ed0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7ee0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7ef0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7f00: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7f10: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7f20: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7f30: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7f40: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7f50: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7f60: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7f70: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7f80: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7f90: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7fa0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7fb0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7fc0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7fd0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7fe0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7ff0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
8000: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
8010: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
8020: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
8030: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
8040: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
8050: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
8060: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
8070: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
8080: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
8090: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
80a0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
80b0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
80c0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
80d0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
80e0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
80f0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
8100: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
8110: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
8120: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
8130: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
8140: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
8150: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
8160: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
8170: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
8180: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
8190: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
81a0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
81b0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
81c0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
81d0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
81e0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
81f0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
8200: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
8210: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
8220: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
8230: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
8240: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
8250: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
8260: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
8270: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
8280: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
8290: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
82a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
82b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
82c0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
82d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
82e0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
82f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8300: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
8310: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8320: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8330: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8340: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8350: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8360: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8370: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8380: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
8390: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
83a0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
83b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
83c0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
83d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
83e0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
83f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8400: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
8410: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8420: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
8430: 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69  HEN_OPEN].** <li
8440: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8450: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
8460: 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ITE].** <li> [SQ
8470: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
8480: 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ABLE].** </ul>.*
8490: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
84a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
84b0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
84c0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
84d0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
84e0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
84f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
8500: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
8510: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
8520: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
8530: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
8540: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
8550: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
8560: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
8570: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
8580: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
8590: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
85a0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
85b0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
85c0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
85d0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
85e0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
85f0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
8600: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
8610: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
8620: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
8630: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
8640: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
8650: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8660: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
8670: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8680: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8690: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
86a0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
86b0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
86c0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
86d0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
86e0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
86f0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
8700: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
8710: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
8720: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
8730: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8740: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
8750: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
8760: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8770: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8780: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8790: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
87a0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
87b0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
87c0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
87d0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
87e0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
87f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8800: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
8810: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
8820: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8830: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8840: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
8850: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
8860: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8870: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8880: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8890: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
88a0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
88b0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
88c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
88d0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
88e0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
88f0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8900: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
8910: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8920: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
8930: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8940: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8950: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8960: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8970: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8980: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8990: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
89a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89b0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
89c0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
89d0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
89e0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
89f0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8a00: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8a10: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8a20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
8a30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8a40: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8a50: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8a60: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8a70: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8a80: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8a90: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8aa0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8ab0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8ac0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8ad0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8ae0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8af0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8b00: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8b10: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8b20: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
8b30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8b40: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8b50: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8b60: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8b70: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8b80: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8b90: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8ba0: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8bb0: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
8bc0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8bd0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8be0: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
8bf0: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8c00: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8c10: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
8c20: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
8c30: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
8c40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8c50: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8c60: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
8c70: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8c80: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8c90: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
8ca0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8cb0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8cc0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
8cd0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
8ce0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
8cf0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
8d00: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
8d10: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
8d20: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
8d30: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8d40: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
8d50: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
8d60: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
8d70: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
8d80: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
8d90: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
8da0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
8db0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
8dc0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8dd0: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
8de0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
8df0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8e00: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
8e10: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8e20: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8e30: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8e40: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8e50: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8e60: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8e70: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8e80: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8e90: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8ea0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8eb0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8ec0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8ed0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8ee0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8ef0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8f00: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
8f10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8f20: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
8f30: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
8f40: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
8f50: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
8f60: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
8f70: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8f80: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
8f90: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
8fa0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
8fb0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
8fc0: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
8fd0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8fe0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8ff0: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
9000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9010: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
9020: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
9030: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
9040: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
9050: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
9060: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
9070: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
9080: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
9090: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
90a0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
90b0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
90c0: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
90d0: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
90e0: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
90f0: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
9100: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
9110: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
9120: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
9130: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
9140: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
9150: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
9160: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
9170: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
9180: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9190: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
91a0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
91b0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
91c0: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
91d0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
91e0: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
91f0: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9200: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9210: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9220: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9230: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9240: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
9250: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
9260: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9270: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
9280: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
9290: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
92a0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
92b0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
92c0: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
92d0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
92e0: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
92f0: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9300: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9310: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9320: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9330: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9340: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9350: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
9360: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
9370: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
9380: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9390: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
93a0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
93b0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
93c0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
93d0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
93e0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
93f0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9400: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9410: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9420: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9440: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
9450: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
9460: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
9470: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9480: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9490: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
94a0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
94b0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
94c0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
94d0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
94e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
94f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9500: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a  iated with the j
9510: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74  ournal file (eit
9520: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c  her.** the [roll
9530: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72  back journal] or
9540: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61   the [write-ahea
9550: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61  d log]) for a pa
9560: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9570: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9580: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
9590: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
95a0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
95b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
95c0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
95d0: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
95e0: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
95f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9600: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9610: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9620: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9630: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9640: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9650: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9660: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9670: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9680: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9690: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
96a0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
96b0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
96c0: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
96d0: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
96e0: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
96f0: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9700: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9710: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9720: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9730: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9740: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9750: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9760: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9770: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9780: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9790: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
97a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
97b0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
97c0: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
97d0: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
97e0: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
97f0: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9800: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9810: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9820: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9830: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9840: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9850: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9860: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9870: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9880: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9890: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
98a0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
98b0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
98c0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
98d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
98e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
98f0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9900: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9910: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9920: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9930: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9940: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9950: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9960: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9970: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9980: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9990: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
99a0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
99b0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
99c0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
99d0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
99e0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
99f0: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9a00: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9a10: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9a20: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9a30: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9a40: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9a50: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9a60: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9a70: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9a80: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9a90: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9aa0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9ab0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9ac0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9ad0: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9ae0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9af0: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9b00: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9b10: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9b20: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9b30: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9b40: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9b50: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9b60: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9b70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9b80: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9b90: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9ba0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9bb0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
9bc0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
9bd0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9be0: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9bf0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
9c00: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
9c10: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9c20: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9c30: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9c40: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9c50: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9c60: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9c70: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9c80: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9c90: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
9ca0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
9cb0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
9cc0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
9cd0: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
9ce0: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
9cf0: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
9d00: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
9d10: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9d20: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9d30: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9d40: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9d50: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9d60: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9d70: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9d80: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9d90: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9da0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9db0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
9dc0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9dd0: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9de0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9df0: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9e00: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9e10: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9e20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9e30: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9e40: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9e50: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9e60: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9e70: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9e80: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9e90: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9ea0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9eb0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9ec0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9ed0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9ee0: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9ef0: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9f00: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9f10: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9f20: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9f30: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9f40: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9f50: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9f60: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9f70: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9f80: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9f90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9fa0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9fb0: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9fc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9fd0: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9fe0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9ff0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a000: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
a010: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
a020: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
a030: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
a040: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
a050: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
a060: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
a070: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
a080: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
a090: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
a0a0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
a0b0: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
a0c0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
a0d0: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
a0e0: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
a0f0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
a100: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
a110: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
a120: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
a130: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
a140: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
a150: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
a160: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
a170: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
a180: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
a190: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
a1a0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
a1b0: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
a1c0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
a1d0: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
a1e0: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
a1f0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
a200: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
a210: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
a220: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
a230: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
a240: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a250: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a260: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a270: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a280: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a290: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a2a0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a2b0: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
a2c0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
a2d0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
a2e0: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
a2f0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a300: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a310: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a320: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a330: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
a340: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
a350: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a360: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a370: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
a380: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a390: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
a3a0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
a3b0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
a3c0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a3d0: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
a3e0: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
a3f0: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
a400: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
a410: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
a420: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
a430: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
a440: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
a450: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a460: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a470: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a480: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a490: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a4a0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a4b0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a4c0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a4d0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a4e0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a4f0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a500: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a510: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a520: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a530: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a540: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a550: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a560: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a570: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a580: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a590: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a5a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a5b0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a5c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a5d0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a5e0: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a5f0: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a600: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a610: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a620: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a630: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a640: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a650: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a660: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a670: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a680: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a690: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a6a0: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a6b0: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a6c0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a6d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a6e0: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a6f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a700: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a710: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a720: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a730: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a740: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a750: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a760: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a770: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a780: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a790: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a7a0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a7b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a7c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a7d0: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a7e0: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a7f0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a800: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a810: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a820: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a830: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a840: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a850: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a860: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a870: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a880: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a890: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a8a0: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a8b0: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a8c0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a8d0: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a8e0: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a8f0: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a900: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a910: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a920: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a930: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a940: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a950: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a960: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a970: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a980: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a990: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a9a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
a9b0: 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  FS_POINTER]].** 
a9c0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a9d0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20  TL_VFS_POINTER] 
a9e0: 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70  opcode finds a p
a9f0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
aa00: 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65  p-level.** [VFSe
aa10: 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20  s] currently in 
aa20: 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75  use.  ^(The argu
aa30: 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c  ment X in.** sql
aa40: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
aa50: 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54  l(db,SQLITE_FCNT
aa60: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29  L_VFS_POINTER,X)
aa70: 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74   must be.** of t
aa80: 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66  ype "[sqlite3_vf
aa90: 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70  s] **".  This op
aaa0: 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a  codes will set *
aab0: 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65  X.** to a pointe
aac0: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
aad0: 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68  el VFS.)^.** ^Wh
aae0: 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c  en there are mul
aaf0: 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20  tiple VFS shims 
ab00: 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68  in the stack, th
ab10: 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  is opcode finds 
ab20: 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73  the.** upper-mos
ab30: 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a  t shim only..**.
ab40: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ab50: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
ab60: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
ab70: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
ab80: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
ab90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
aba0: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
abb0: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
abc0: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
abd0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
abe0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
abf0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
ac00: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
ac10: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
ac20: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
ac30: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
ac40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
ac50: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
ac60: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
ac70: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
ac80: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
ac90: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
aca0: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
acb0: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
acc0: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
acd0: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
ace0: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
acf0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
ad00: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
ad10: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
ad20: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
ad30: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
ad40: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
ad50: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
ad60: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
ad70: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
ad80: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
ad90: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
ada0: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
adb0: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
adc0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
add0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
ade0: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
adf0: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
ae00: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
ae10: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
ae20: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
ae30: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
ae40: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
ae50: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
ae60: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
ae70: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
ae80: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
ae90: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
aea0: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
aeb0: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
aec0: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
aed0: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
aee0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
aef0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
af00: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
af10: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
af20: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
af30: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
af40: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
af50: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
af60: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
af70: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
af80: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
af90: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75  tatement if resu
afa0: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c  lt string is NUL
afb0: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72  L, or that retur
afc0: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  ns a copy.** of 
afd0: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e  the result strin
afe0: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  g if the string 
aff0: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20  is non-NULL..** 
b000: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
b010: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b020: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b030: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
b040: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
b050: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
b060: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
b070: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
b080: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
b090: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
b0a0: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
b0b0: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
b0c0: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
b0d0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
b0e0: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
b0f0: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
b100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b110: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
b120: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
b130: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
b140: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
b150: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
b160: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
b170: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
b180: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
b190: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
b1a0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b1b0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
b1c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
b1d0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b1e0: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
b1f0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
b200: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
b210: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b220: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
b230: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
b240: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
b250: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
b260: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
b270: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
b280: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
b290: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
b2a0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b2b0: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
b2c0: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
b2d0: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
b2e0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
b2f0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
b300: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
b310: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
b320: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
b330: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
b340: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
b350: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
b360: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
b370: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
b380: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
b390: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
b3a0: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
b3b0: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
b3c0: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
b3d0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
b3e0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
b3f0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
b400: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
b410: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
b420: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
b430: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
b440: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
b450: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
b460: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b470: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
b480: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
b490: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
b4a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b4b0: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
b4c0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
b4d0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
b4e0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
b4f0: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
b500: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
b510: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
b520: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
b530: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b540: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
b550: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
b560: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
b570: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
b580: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
b590: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
b5a0: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
b5b0: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
b5c0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
b5d0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
b5e0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
b5f0: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
b600: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
b610: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
b620: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
b630: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
b640: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
b650: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b660: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
b670: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b680: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
b690: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b6a0: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
b6b0: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
b6c0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b6d0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
b6e0: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
b6f0: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
b700: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
b710: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
b720: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
b730: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
b740: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
b750: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b760: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
b770: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
b780: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
b790: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
b7a0: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
b7b0: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
b7c0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
b7d0: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
b7e0: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
b7f0: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
b800: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
b810: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
b820: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
b830: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
b840: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
b850: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
b860: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
b870: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
b880: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
b890: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
b8a0: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ize]..**.** <li>
b8b0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b8c0: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RACE]].** The [S
b8d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b8e0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b8f0: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72  provides advisor
b900: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  y information.**
b910: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75   to the VFS abou
b920: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65  t what the highe
b930: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20  r layers of the 
b940: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65  SQLite stack are
b950: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20   doing..** This 
b960: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b970: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53  used by some VFS
b980: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e   activity tracin
b990: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68  g [shims]..** Th
b9a0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b9b0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
b9c0: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20  string.  Higher 
b9d0: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  layers in the.**
b9e0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61   SQLite stack ma
b9f0: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61  y generate insta
ba00: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c  nces of this fil
ba10: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20  e control if.** 
ba20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
ba30: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d  FCNTL_TRACE] com
ba40: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
ba50: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
ba60: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ba70: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
ba80: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
ba90: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
baa0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
bab0: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
bac0: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70  gument as a.** p
bad0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
bae0: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74  eger and it writ
baf0: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74  es a boolean int
bb00: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64  o that integer d
bb10: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77  epending.** on w
bb20: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
bb30: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20  e file has been 
bb40: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20  renamed, moved, 
bb50: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65  or deleted since
bb60: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74   it.** was first
bb70: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c   opened..**.** <
bb80: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bb90: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
bba0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
bbb0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bbc0: 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  GET_HANDLE] opco
bbd0: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
bbe0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20  o obtain the.** 
bbf0: 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76  underlying nativ
bc00: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73  e file handle as
bc10: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
bc20: 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68  file handle.  Th
bc30: 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72  is file.** contr
bc40: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bc50: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20  s argument as a 
bc60: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74  pointer to a nat
bc70: 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  ive file handle 
bc80: 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68  and.** writes th
bc90: 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75  e resulting valu
bca0: 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c  e there..**.** <
bcb0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bcc0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
bcd0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
bce0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bcf0: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  SET_HANDLE] opco
bd00: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
bd10: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
bd20: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
bd30: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
bd40: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70  l method to swap
bd50: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65   the file handle
bd60: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a   with the one.**
bd70: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
bd80: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
bd90: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  .  This capabili
bda0: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ty is used durin
bdb0: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64  g testing.** and
bdc0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
bdd0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
bde0: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20   SQLITE_TEST is 
bdf0: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
be00: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
be10: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a  L_WAL_BLOCK]].**
be20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
be30: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73  TL_WAL_BLOCK] is
be40: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65   a signal to the
be50: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20   VFS layer that 
be60: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61  it might.** be a
be70: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62  dvantageous to b
be80: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74  lock on the next
be90: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65   WAL lock if the
bea0: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d   lock is not imm
beb0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69  ediately.** avai
bec0: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20  lable.  The WAL 
bed0: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73  subsystem issues
bee0: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72   this signal dur
bef0: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63  ing rare.** circ
bf00: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64  umstances in ord
bf10: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62  er to fix a prob
bf20: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74  lem with priorit
bf30: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20  y inversion..** 
bf40: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
bf50: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e  uld <em>not</em>
bf60: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63   use this file-c
bf70: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ontrol..**.** <l
bf80: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bf90: 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65  _ZIPVFS]].** The
bfa0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a   [SQLITE_FCNTL_Z
bfb0: 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73  IPVFS] opcode is
bfc0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
bfd0: 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c  zipvfs only. All
bfe0: 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68   other.** VFS sh
bff0: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49  ould return SQLI
c000: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20  TE_NOTFOUND for 
c010: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a  this opcode..**.
c020: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c030: 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54  FCNTL_RBU]].** T
c040: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c050: 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20  _RBU] opcode is 
c060: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74  implemented by t
c070: 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75  he special VFS u
c080: 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42  sed by.** the RB
c090: 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79  U extension only
c0a0: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53  .  All other VFS
c0b0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c0c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c0d0: 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64  or.** this opcod
c0e0: 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  e.  .** </ul>.*/
c0f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c100: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
c110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
c120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c130: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
c140: 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23  XYFILE       2.#
c150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c160: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
c170: 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64  YFILE       3.#d
c180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c190: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TL_LAST_ERRNO   
c1a0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
c1b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c1c0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
c1d0: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
c1e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c1f0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
c200: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
c210: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c220: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
c230: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
c240: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c250: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
c260: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
c270: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
c280: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
c290: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
c2a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
c2b0: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
c2c0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
c2d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
c2e0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
c2f0: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
c300: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
c310: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
c320: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
c330: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
c340: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
c350: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
c360: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
c370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c380: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
c390: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
c3a0: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
c3b0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
c3c0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
c3d0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
c3e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c3f0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
c400: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
c410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c420: 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20  CNTL_TRACE      
c430: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23              19.#
c440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c450: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20  NTL_HAS_MOVED   
c460: 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64             20.#d
c470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c480: 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20  TL_SYNC         
c490: 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65            21.#de
c4a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c4b0: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
c4c0: 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66  O        22.#def
c4d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c4e0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c4f0: 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69  E       23.#defi
c500: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c510: 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20  WAL_BLOCK       
c520: 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e         24.#defin
c530: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a  e SQLITE_FCNTL_Z
c540: 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20  IPVFS           
c550: 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65        25.#define
c560: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42   SQLITE_FCNTL_RB
c570: 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  U               
c580: 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20       26.#define 
c590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
c5a0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
c5b0: 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53      27.#define S
c5c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
c5d0: 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  NAL_POINTER     
c5e0: 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51     28.#define SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c600: 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _GET_HANDLE     
c610: 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    29.#define SQL
c620: 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20  ITE_FCNTL_PDB   
c630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c640: 20 33 30 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74   30../* deprecat
c650: 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66  ed names */.#def
c660: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
c670: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
c680: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47    SQLITE_FCNTL_G
c690: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c6a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c6b0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c6c0: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
c6d0: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
c6e0: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
c6f0: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
c700: 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49              SQLI
c710: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
c720: 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  RNO.../*.** CAPI
c730: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
c740: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
c750: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
c760: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
c770: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
c780: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
c790: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
c7a0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
c7b0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
c7c0: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
c7d0: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
c7e0: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
c7f0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
c800: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
c810: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
c820: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
c830: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
c840: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
c850: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
c860: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
c870: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
c880: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
c890: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
c8a0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
c8b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
c8c0: 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54  able Extension T
c8d0: 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  hunk.**.** A poi
c8e0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71  nter to the opaq
c8f0: 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ue sqlite3_api_r
c900: 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72  outines structur
c910: 65 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a  e is passed as.*
c920: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
c930: 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70  meter to entry p
c940: 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62  oints of [loadab
c950: 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20  le extensions]. 
c960: 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75   This.** structu
c970: 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64  re must be typed
c980: 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  efed in order to
c990: 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d   work around com
c9a0: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a  piler warnings.*
c9b0: 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f  * on some platfo
c9c0: 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  rms..*/.typedef 
c9d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
c9e0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69  pi_routines sqli
c9f0: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
ca00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ca10: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
ca20: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
ca30: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
ca40: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
ca50: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
ca60: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
ca70: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
ca80: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
ca90: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
caa0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
cab0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
cac0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
cad0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
cae0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
caf0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
cb00: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
cb10: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
cb20: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
cb30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
cb40: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
cb50: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
cb60: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
cb70: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
cb80: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
cb90: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
cba0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
cbb0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
cbc0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
cbd0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
cbe0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
cbf0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
cc00: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
cc10: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
cc20: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
cc30: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
cc40: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
cc50: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
cc60: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
cc70: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
cc80: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
cc90: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
cca0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
ccb0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
ccc0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
ccd0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
cce0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
ccf0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
cd00: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
cd10: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
cd20: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
cd30: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
cd40: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
cd50: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
cd60: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
cd70: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
cd80: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
cd90: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
cda0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
cdb0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
cdc0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
cdd0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
cde0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
cdf0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
ce00: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
ce10: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
ce20: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
ce30: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
ce40: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
ce50: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
ce60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
ce70: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
ce80: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
ce90: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
cea0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
ceb0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
cec0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
ced0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
cee0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
cef0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
cf00: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
cf10: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
cf20: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
cf30: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
cf40: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
cf50: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
cf60: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
cf70: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
cf80: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
cf90: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
cfa0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
cfb0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
cfc0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
cfd0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
cfe0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
cff0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
d000: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
d010: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
d020: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
d030: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
d040: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
d050: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
d060: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
d070: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
d080: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
d090: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
d0a0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
d0b0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
d0c0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
d0d0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
d0e0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
d0f0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
d100: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
d110: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
d120: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
d130: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d140: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
d150: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
d160: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
d170: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
d180: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
d190: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
d1a0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
d1b0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
d1c0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
d1d0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
d1e0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
d1f0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
d200: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
d210: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
d220: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
d230: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
d240: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
d250: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
d260: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
d270: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
d280: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
d290: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
d2a0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
d2b0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
d2c0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
d2d0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
d2e0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
d2f0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
d300: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
d310: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
d320: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
d330: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
d340: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
d350: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
d360: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
d370: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
d380: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
d390: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
d3a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d3b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
d3c0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
d3d0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
d3e0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
d3f0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
d400: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d410: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
d420: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
d430: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
d440: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
d450: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
d460: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
d470: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
d480: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
d490: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
d4a0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d4b0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
d4c0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
d4d0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
d4e0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
d4f0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
d500: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
d510: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
d520: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
d530: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
d540: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
d550: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
d560: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
d570: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
d580: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
d590: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
d5a0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
d5b0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
d5c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d5d0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
d5e0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d5f0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
d600: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d610: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
d620: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d630: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
d640: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d650: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
d660: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
d670: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
d680: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
d690: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d6a0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
d6b0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d6c0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
d6d0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
d6e0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
d6f0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
d700: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
d710: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
d720: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
d730: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
d740: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
d750: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
d760: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
d770: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
d780: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
d790: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
d7a0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
d7b0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
d7c0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
d7d0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
d7e0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
d7f0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
d800: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
d810: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
d820: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
d830: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
d840: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d850: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
d860: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
d870: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
d880: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
d890: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
d8a0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
d8b0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
d8c0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
d8d0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
d8e0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
d8f0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
d900: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
d910: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
d920: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
d930: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
d940: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d950: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
d960: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
d970: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
d980: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
d990: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
d9a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
d9b0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
d9c0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
d9d0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
d9e0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
d9f0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
da00: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
da10: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
da20: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
da30: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
da40: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
da50: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
da60: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
da70: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
da80: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
da90: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
daa0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
dab0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
dac0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
dad0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
dae0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
daf0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
db00: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
db10: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
db20: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
db30: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
db40: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
db50: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
db60: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
db70: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
db80: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
db90: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
dba0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
dbb0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
dbc0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
dbd0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
dbe0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
dbf0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
dc00: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
dc10: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
dc20: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
dc30: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
dc40: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
dc50: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
dc60: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
dc70: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
dc80: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
dc90: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
dca0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
dcb0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
dcc0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
dcd0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
dce0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
dcf0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
dd00: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
dd10: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
dd20: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
dd30: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
dd40: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
dd50: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
dd60: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
dd70: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
dd80: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
dd90: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
dda0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
ddb0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
ddc0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
ddd0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
dde0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
ddf0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
de00: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
de10: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
de20: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
de30: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
de40: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
de50: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
de60: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
de70: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
de80: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
de90: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
dea0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
deb0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
dec0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
ded0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
dee0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
def0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
df00: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
df10: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
df20: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
df30: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
df40: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
df50: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
df60: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
df70: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
df80: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
df90: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
dfa0: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
dfb0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
dfc0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
dfd0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
dfe0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
dff0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
e000: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
e010: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
e020: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
e030: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
e040: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
e050: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
e060: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
e070: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
e080: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
e090: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
e0a0: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
e0b0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
e0c0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
e0d0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
e0e0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
e0f0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
e100: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
e110: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
e120: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
e130: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
e140: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
e150: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
e160: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
e170: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
e180: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
e190: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
e1a0: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
e1b0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e1c0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
e1d0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
e1e0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
e1f0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
e200: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
e210: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
e220: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
e230: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
e240: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
e250: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
e260: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
e270: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
e280: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
e290: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
e2a0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
e2b0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
e2c0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
e2d0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
e2e0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
e2f0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
e300: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
e310: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
e320: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
e330: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
e340: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
e350: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
e360: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
e370: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
e380: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
e390: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
e3a0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
e3b0: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
e3c0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
e3d0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
e3e0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
e3f0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
e400: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
e410: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
e420: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
e430: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
e440: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
e450: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
e460: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
e470: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
e480: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
e490: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
e4a0: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
e4b0: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
e4c0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
e4d0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
e4e0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
e4f0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
e500: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
e510: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
e520: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
e530: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
e540: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
e550: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
e560: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
e570: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
e580: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
e590: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
e5a0: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
e5b0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
e5c0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
e5d0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
e5e0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
e5f0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
e600: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
e610: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
e620: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
e630: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
e640: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
e650: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
e660: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
e670: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
e680: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
e690: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
e6a0: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
e6b0: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
e6c0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
e6d0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
e6e0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
e6f0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
e700: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
e710: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
e720: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
e730: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
e740: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
e750: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
e760: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
e770: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
e780: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
e790: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
e7a0: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
e7b0: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
e7c0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
e7d0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
e7e0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
e7f0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
e800: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
e810: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
e820: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
e830: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
e840: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
e850: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
e860: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
e870: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
e880: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
e890: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
e8a0: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
e8b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
e8c0: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
e8d0: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
e8e0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e8f0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
e900: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
e910: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
e920: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
e930: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
e940: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
e950: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
e960: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
e970: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
e980: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
e990: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
e9a0: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
e9b0: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
e9c0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
e9d0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
e9e0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
e9f0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
ea00: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
ea10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ea20: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
ea30: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
ea40: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
ea50: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
ea60: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
ea70: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
ea80: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
ea90: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
eaa0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
eab0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
eac0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
ead0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
eae0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
eaf0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
eb00: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
eb10: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eb20: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
eb30: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
eb40: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
eb50: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eb60: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
eb70: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
eb80: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
eb90: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
eba0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ebb0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ebc0: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
ebd0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
ebe0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
ebf0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ec00: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
ec10: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
ec20: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
ec30: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
ec40: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
ec50: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
ec60: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
ec70: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
ec80: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
ec90: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
eca0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
ecb0: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
ecc0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
ecd0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ece0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
ecf0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
ed00: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
ed10: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
ed20: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
ed30: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
ed40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
ed50: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
ed60: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
ed70: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
ed80: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
ed90: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
eda0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
edb0: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
edc0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
edd0: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
ede0: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
edf0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
ee00: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
ee10: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
ee20: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
ee30: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
ee40: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
ee50: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
ee60: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
ee70: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
ee80: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
ee90: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
eea0: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
eeb0: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
eec0: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
eed0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
eee0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
eef0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ef00: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
ef10: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
ef20: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
ef30: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
ef40: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ef50: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ef60: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
ef70: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
ef80: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
ef90: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
efa0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
efb0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
efc0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
efd0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
efe0: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
eff0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
f000: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
f010: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
f020: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
f030: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
f040: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
f050: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
f060: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
f070: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
f080: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f090: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
f0a0: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
f0b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
f0c0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
f0d0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
f0e0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
f0f0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
f100: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
f110: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
f120: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
f130: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
f140: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
f150: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
f160: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
f170: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
f180: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
f190: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
f1a0: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
f1b0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
f1c0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
f1d0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f1e0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f1f0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
f200: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
f210: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
f220: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
f230: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
f240: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
f250: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
f260: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
f270: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
f280: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
f290: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
f2a0: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
f2b0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f2c0: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
f2d0: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
f2e0: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
f2f0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
f300: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
f310: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
f320: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
f330: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
f340: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
f350: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f360: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
f370: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
f380: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
f390: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
f3a0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
f3b0: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
f3c0: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
f3d0: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
f3e0: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
f3f0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
f400: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
f410: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f420: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
f430: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
f440: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f450: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
f460: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
f470: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
f480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f490: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
f4a0: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
f4b0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
f4c0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
f4d0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
f4e0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
f4f0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
f500: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
f510: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
f520: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
f530: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
f540: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
f550: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f560: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
f570: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
f580: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
f590: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
f5a0: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
f5b0: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
f5c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
f5d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f5e0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
f5f0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
f600: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
f610: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
f620: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
f630: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
f640: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f650: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
f660: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
f670: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
f680: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
f690: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
f6a0: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
f6b0: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
f6c0: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
f6d0: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
f6e0: 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
f6f0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
f700: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
f710: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
f720: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
f730: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
f740: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
f750: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
f760: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
f770: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
f780: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
f790: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
f7a0: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
f7b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
f7c0: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
f7d0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
f7e0: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
f7f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f800: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
f810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f820: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
f830: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f840: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
f850: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
f860: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f870: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
f880: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
f890: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
f8a0: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
f8b0: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
f8c0: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
f8d0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
f8e0: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
f8f0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
f900: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
f910: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
f920: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
f930: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
f940: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
f950: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
f960: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
f970: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
f980: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
f990: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f9a0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
f9b0: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
f9c0: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
f9d0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
f9e0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
f9f0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
fa00: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
fa10: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
fa20: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
fa30: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
fa40: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
fa50: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
fa60: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
fa70: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
fa80: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
fa90: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
faa0: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
fab0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
fac0: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
fad0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
fae0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
faf0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
fb00: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
fb10: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
fb20: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
fb30: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
fb40: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
fb50: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
fb60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fb70: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
fb80: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
fb90: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
fba0: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
fbb0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
fbc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fbd0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
fbe0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
fbf0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fc00: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
fc10: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
fc20: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
fc30: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
fc40: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
fc50: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
fc60: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
fc70: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
fc80: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
fc90: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fca0: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
fcb0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
fcc0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
fcd0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
fce0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
fcf0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
fd00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fd10: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
fd20: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
fd30: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fd40: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
fd50: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
fd60: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
fd70: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
fd80: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
fd90: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
fda0: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
fdb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fdc0: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
fdd0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
fde0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
fdf0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
fe00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
fe10: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
fe20: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
fe30: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
fe40: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
fe50: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
fe60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
fe70: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
fe80: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
fe90: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
fea0: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
feb0: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
fec0: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
fed0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
fee0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
fef0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
ff00: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
ff10: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
ff20: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
ff30: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
ff40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
ff50: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
ff60: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
ff70: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
ff80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ff90: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
ffa0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
ffb0: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
ffc0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
ffd0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ffe0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
fff0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
10000 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
10010 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
10020 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
10030 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
10040 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
10050 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
10060 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
10070 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
10080 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
10090 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
100a0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
100b0 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
100c0 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
100d0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
100e0 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
100f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
10100 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
10110 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
10120 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10130 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
10140 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
10150 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
10160 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
10170 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
10180 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10190 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
101a0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
101b0 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
101c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
101d0 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
101e0 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
101f0 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
10200 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
10210 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10220 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
10230 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
10240 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
10250 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
10260 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
10270 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
10280 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
10290 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
102a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
102b0 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
102c0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
102d0 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
102e0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
102f0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10300 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
10310 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
10320 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
10330 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
10340 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
10350 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
10360 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
10370 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
10380 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
10390 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
103a0 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
103b0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
103c0 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
103d0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
103e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
103f0 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
10400 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10410 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
10420 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
10430 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
10440 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
10450 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
10460 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
10470 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
10480 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10490 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
104a0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
104b0 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
104c0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
104d0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
104e0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
104f0 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
10500 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
10510 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
10520 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
10530 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
10540 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
10550 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
10560 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
10570 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
10580 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
10590 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
105a0 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
105b0 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
105c0 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
105d0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
105e0 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
105f0 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
10600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
10610 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
10620 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
10630 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
10640 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
10650 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
10660 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
10670 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
10680 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
10690 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
106a0 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
106b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
106c0 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
106d0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
106e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
106f0 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
10700 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
10710 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
10720 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10730 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
10740 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
10750 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
10760 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
10770 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
10780 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
10790 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
107a0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
107b0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
107c0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
107d0 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
107e0 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
107f0 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
10800 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
10810 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
10820 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
10830 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
10840 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
10850 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
10860 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
10870 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
10880 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
10890 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
108a0 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
108b0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
108c0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
108d0 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
108e0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
108f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10900 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
10910 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
10920 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
10930 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
10940 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
10950 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
10960 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
10970 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
10980 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
10990 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
109a0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
109b0 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
109c0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
109d0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
109e0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
109f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10a00 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
10a10 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
10a20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10a30 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
10a40 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
10a50 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
10a60 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
10a70 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
10a80 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
10a90 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
10aa0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
10ab0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10ac0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
10ad0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
10ae0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
10af0 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
10b00 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
10b10 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
10b20 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
10b30 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
10b40 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
10b50 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
10b60 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
10b70 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
10b80 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10b90 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10ba0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
10bb0 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
10bc0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
10bd0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
10be0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
10bf0 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
10c00 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
10c10 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
10c20 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
10c30 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
10c40 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10c50 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
10c60 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
10c70 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
10c80 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
10c90 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
10ca0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10cb0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
10cc0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
10cd0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
10ce0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
10cf0 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
10d00 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
10d10 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
10d20 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
10d30 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10d40 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
10d50 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
10d60 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
10d70 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
10d80 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
10d90 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
10da0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
10db0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
10dc0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
10dd0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
10de0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
10df0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
10e00 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
10e10 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
10e20 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
10e30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
10e40 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
10e50 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
10e60 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
10e70 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
10e80 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10e90 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
10ea0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
10eb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10ec0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
10ed0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
10ee0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
10ef0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10f00 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
10f10 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
10f20 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
10f30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
10f40 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
10f50 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
10f60 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
10f70 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
10f80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10f90 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
10fa0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
10fb0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10fc0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
10fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
10fe0 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
10ff0 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
11000 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
11010 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11020 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
11030 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
11040 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
11050 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11060 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
11070 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
11080 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
11090 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
110a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
110b0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
110c0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
110d0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
110e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
110f0 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
11100 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11110 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
11120 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11130 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11140 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
11150 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
11160 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
11170 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
11180 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
11190 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
111a0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
111b0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
111c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
111d0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
111e0 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
111f0 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
11200 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
11210 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
11220 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
11230 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
11240 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11250 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
11260 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
11270 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
11280 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
11290 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
112a0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
112b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
112c0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
112d0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
112e0 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
112f0 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
11300 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11310 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
11320 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
11330 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
11340 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
11350 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11360 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
11370 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
11380 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
11390 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
113a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
113b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
113c0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
113d0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
113e0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
113f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11400 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
11410 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
11420 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11430 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
11440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
11450 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
11460 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
11470 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11480 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
11490 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
114a0 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
114b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
114c0 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
114d0 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
114e0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
114f0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
11500 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
11510 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
11520 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
11530 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
11540 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
11550 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
11560 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
11570 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
11580 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
11590 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
115a0 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
115b0 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
115c0 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
115d0 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
115e0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
115f0 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
11600 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
11610 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
11620 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
11630 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
11640 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
11650 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11660 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
11670 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
11680 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
11690 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
116a0 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
116b0 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
116c0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
116d0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
116e0 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
116f0 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
11700 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
11710 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
11720 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
11730 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
11740 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
11750 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
11760 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
11770 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
11780 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
11790 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
117a0 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
117b0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
117c0 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
117d0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
117e0 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
117f0 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
11800 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
11810 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
11820 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
11830 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
11840 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
11850 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
11860 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
11870 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
11880 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
11890 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
118a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
118b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
118c0 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
118d0 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
118e0 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
118f0 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
11900 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
11910 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
11920 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
11930 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
11940 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
11950 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
11960 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
11970 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
11980 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
11990 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
119a0 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
119b0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
119c0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
119d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
119e0 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
119f0 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
11a00 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
11a10 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
11a20 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
11a30 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
11a40 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
11a50 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
11a60 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
11a70 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
11a80 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
11a90 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
11aa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
11ab0 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
11ac0 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
11ad0 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
11ae0 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
11af0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
11b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11b10 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
11b20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
11b30 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
11b40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11b50 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
11b60 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
11b70 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
11b80 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
11b90 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
11ba0 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
11bb0 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
11bc0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
11bd0 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
11be0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
11bf0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
11c00 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
11c10 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
11c20 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
11c30 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
11c40 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
11c50 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
11c60 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
11c70 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
11c80 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
11c90 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
11ca0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
11cb0 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
11cc0 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
11cd0 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
11ce0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
11cf0 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
11d00 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
11d10 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
11d20 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
11d30 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
11d40 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11d50 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
11d60 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
11d70 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
11d80 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
11d90 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
11da0 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
11db0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11dc0 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
11dd0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
11de0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
11df0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
11e00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11e10 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
11e20 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
11e30 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
11e40 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
11e50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
11e60 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
11e70 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
11e80 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11e90 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
11ea0 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
11eb0 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
11ec0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
11ed0 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
11ee0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
11ef0 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
11f00 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
11f10 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
11f20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
11f30 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
11f40 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
11f50 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
11f60 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
11f70 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
11f80 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11f90 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
11fa0 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
11fb0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11fc0 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
11fd0 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
11fe0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
11ff0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
12000 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
12010 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
12020 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
12030 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
12040 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
12050 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
12060 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
12070 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
12080 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
12090 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
120a0 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
120b0 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
120c0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
120d0 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
120e0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
120f0 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
12100 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
12110 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
12120 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
12130 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
12140 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
12150 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
12160 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
12170 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
12180 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
12190 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
121a0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
121b0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
121c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
121d0 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
121e0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
121f0 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
12200 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
12210 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
12220 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
12230 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12240 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
12250 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
12260 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
12270 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
12280 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
12290 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
122a0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
122b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
122c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
122d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
122e0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
122f0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
12300 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
12310 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
12320 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
12330 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12340 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
12350 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
12360 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
12370 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
12380 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
12390 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
123a0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
123b0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
123c0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
123d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
123e0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
123f0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
12400 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
12410 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
12420 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
12430 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
12440 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
12450 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
12460 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
12470 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12480 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
12490 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
124a0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
124b0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
124c0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
124d0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
124e0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
124f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12500 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
12510 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
12520 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
12530 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
12540 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
12550 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
12560 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
12570 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
12580 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
12590 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
125a0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
125b0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
125c0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
125d0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
125e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
125f0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12600 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
12610 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
12620 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
12630 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
12640 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
12650 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
12660 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12670 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
12680 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12690 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
126a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
126b0 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
126c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
126d0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
126e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
126f0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
12700 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12710 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
12720 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
12730 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
12740 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
12750 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
12760 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
12770 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
12780 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
12790 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
127a0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
127b0 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
127c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
127d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
127e0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
127f0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
12800 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
12810 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
12820 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
12830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12840 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
12850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
12860 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
12870 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
12880 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
12890 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
128a0 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
128b0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
128c0 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
128d0 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
128e0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
128f0 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
12900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12910 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
12920 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
12930 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12940 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
12950 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
12960 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12970 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12980 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12990 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
129a0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
129b0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
129c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
129d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
129e0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
129f0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
12a00 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12a10 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
12a20 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
12a30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12a40 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12a50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12a60 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
12a70 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12a80 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
12a90 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
12aa0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
12ab0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
12ac0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
12ad0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
12ae0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
12af0 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
12b00 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
12b10 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
12b20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
12b30 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
12b40 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
12b50 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
12b60 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
12b70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12b80 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
12b90 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
12ba0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
12bb0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
12bc0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12bd0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12be0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
12bf0 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
12c00 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
12c10 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
12c20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12c30 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
12c40 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
12c50 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
12c60 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
12c70 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
12c80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12c90 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
12ca0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
12cb0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
12cc0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
12cd0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
12ce0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
12cf0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12d00 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12d10 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
12d20 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
12d30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
12d40 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
12d50 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12d60 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
12d70 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
12d80 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
12d90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12da0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
12db0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12dc0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12dd0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12de0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
12df0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12e00 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12e10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12e20 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
12e30 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
12e40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12e50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12e60 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
12e70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12e80 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
12e90 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
12ea0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12eb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12ec0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12ed0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
12ee0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
12ef0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
12f00 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
12f10 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12f20 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
12f30 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
12f40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12f50 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
12f60 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
12f70 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
12f80 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
12f90 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
12fa0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
12fb0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12fc0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
12fd0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
12fe0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
12ff0 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
13000 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13010 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
13020 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13030 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
13040 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13050 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13060 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
13070 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13080 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
13090 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
130a0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
130b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
130c0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
130d0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
130e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
130f0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
13100 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
13110 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
13120 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
13130 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
13140 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
13150 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
13160 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
13170 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
13180 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
13190 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
131a0 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
131b0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
131c0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
131d0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
131e0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
131f0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
13200 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13210 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
13220 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13230 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
13240 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13250 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13260 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
13270 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13280 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
13290 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
132a0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
132b0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
132c0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
132d0 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
132e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
132f0 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
13300 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13310 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
13320 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
13330 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
13340 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
13350 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
13360 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
13370 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
13380 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
13390 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
133a0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
133b0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
133c0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
133d0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
133e0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
133f0 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
13400 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
13410 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13420 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
13430 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
13440 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
13450 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
13460 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
13470 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
13480 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
13490 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
134a0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
134b0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
134c0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
134d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
134e0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
134f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13500 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
13510 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
13520 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13530 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  TCH option speci
13540 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13550 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74  mory buffer.** t
13560 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
13570 73 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d  se for scratch m
13580 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20  emory.  ^(There 
13590 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
135a0 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45  nts.** to SQLITE
135b0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a  _CONFIG_SCRATCH:
135c0 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
135d0 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
135e0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
135f0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
13600 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
13610 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
13620 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
13630 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
13640 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
13650 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
13660 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
13670 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
13680 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72  N).)^.** The fir
13690 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
136a0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
136b0 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
136c0 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
136d0 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
136e0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
136f0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
13700 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e  ot use more than
13710 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66   one scratch buf
13720 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e  fers per thread.
13730 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
13740 20 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61   never request a
13750 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
13760 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
13770 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
13780 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
13790 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ize..** ^If SQLi
137a0 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
137b0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
137c0 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
137d0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
137e0 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
137f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13800 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
13810 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
13820 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
13830 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
13840 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57  needed.<p>.** ^W
13850 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74  hen the applicat
13860 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79  ion provides any
13870 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74   amount of scrat
13880 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a  ch memory using.
13890 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
138a0 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65  _SCRATCH, SQLite
138b0 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73   avoids unnecess
138c0 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71  ary large.** [sq
138d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61  lite3_malloc|hea
138e0 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a  p allocations]..
138f0 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70  ** This can help
13900 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70   [Robson proof|p
13910 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c  revent memory al
13920 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
13930 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a  s] due to heap.*
13940 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  * fragmentation 
13950 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d  in low-memory em
13960 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a  bedded systems..
13970 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
13980 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13990 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
139a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
139b0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
139c0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
139d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
139e0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
139f0 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a  s a memory pool.
13a00 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
13a10 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64  an use for the d
13a20 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
13a30 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
13a40 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ult page.** cach
13a50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13a60 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
13a70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13a80 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61   is a no-op if a
13a90 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
13aa0 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
13ab0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13ac0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
13ad0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
13ae0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a  NFIG_PCACHE2]..*
13af0 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
13b00 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
13b10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13b20 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74  GECACHE: A point
13b30 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20  er to.** 8-byte 
13b40 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28  aligned memory (
13b50 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20  pMem), the size 
13b60 6f 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63  of each page cac
13b70 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a  he line (sz),.**
13b80 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
13b90 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28  of cache lines (
13ba0 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
13bb0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
13bc0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
13bd0 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
13be0 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
13bf0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
13c00 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
13c10 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
13c20 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
13c30 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
13c40 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
13c50 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
13c60 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
13c70 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
13c80 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
13c90 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13ca0 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a  PCACHE_HDRSZ]..*
13cb0 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73  * ^It is harmles
13cc0 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
13cd0 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
13ce0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70  .** for the sz p
13cf0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c  arameter to be l
13d00 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73  arger than neces
13d10 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a  sary.  The pMem.
13d20 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
13d30 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
13d40 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70  L pointer or a p
13d50 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
13d60 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62  yte.** aligned b
13d70 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f  lock of memory o
13d80 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
13d90 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65  bytes, otherwise
13da0 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62  .** subsequent b
13db0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
13dc0 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70  ined..** ^When p
13dd0 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  Mem is not NULL,
13de0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72   SQLite will str
13df0 69 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d  ive to use the m
13e00 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a  emory provided.*
13e10 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67  * to satisfy pag
13e20 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66  e cache needs, f
13e30 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b  alling back to [
13e40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13e50 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63  ] if.** a page c
13e60 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72  ache line is lar
13e70 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65  ger than sz byte
13e80 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74  s or if all of t
13e90 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a  he pMem buffer.*
13ea0 2a 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a  * is exhausted..
13eb0 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e  ** ^If pMem is N
13ec0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e  ULL and N is non
13ed0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68  -zero, then each
13ee0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13ef0 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20  tion.** does an 
13f00 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c  initial bulk all
13f10 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65  ocation for page
13f20 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a   cache memory.**
13f30 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
13f40 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69  alloc()] suffici
13f50 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20  ent for N cache 
13f60 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f  lines if N is po
13f70 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20  sitive or.** of 
13f80 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66  -1024*N bytes if
13f90 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20   N is negative, 
13fa0 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  . ^If additional
13fb0 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
13fc0 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
13fd0 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
13fe0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69  rovided by the i
13ff0 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61  nitial.** alloca
14000 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74  tion, then SQLit
14010 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
14020 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70  e3_malloc()] sep
14030 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68  arately for each
14040 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  .** additional c
14050 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e  ache line. </dd>
14060 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14070 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
14080 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14090 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
140a0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
140b0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
140c0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
140d0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
140e0 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
140f0 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
14100 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
14110 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
14120 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
14130 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
14140 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
14150 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14160 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
14170 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14180 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  E]..** ^The SQLI
14190 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
141a0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
141b0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
141c0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  e is compiled.**
141d0 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51   with either [SQ
141e0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
141f0 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  YS3] or [SQLITE_
14200 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
14210 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  and returns.** [
14220 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
14230 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69   invoked otherwi
14240 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  se..** ^There ar
14250 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
14260 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
14270 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38  IG_HEAP:.** An 8
14280 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
14290 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
142a0 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
142b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
142c0 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
142d0 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
142e0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
142f0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
14300 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14310 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
14320 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
14330 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
14340 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
14350 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
14360 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
14370 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
14380 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
14390 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
143a0 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
143b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
143c0 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
143d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
143e0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  er is not NULL t
143f0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
14400 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
14410 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
14420 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
14430 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
14440 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14450 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
14460 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
14470 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
14480 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
14490 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
144a0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
144b0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
144c0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
144d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
144e0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
144f0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
14500 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
14510 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
14520 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
14530 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
14540 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
14550 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
14560 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14570 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
14580 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14590 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
145a0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
145b0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74  CONFIG_MUTEX opt
145c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
145d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
145e0 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  h is a.** pointe
145f0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14600 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14610 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14620 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
14630 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
14640 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65  fies alternative
14650 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
14660 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
14670 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65  used.** in place
14680 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
14690 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
146a0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
146b0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
146c0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
146d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
146e0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
146f0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
14700 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
14710 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14720 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
14730 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14740 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
14750 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14760 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14770 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14780 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14790 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
147a0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
147b0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
147c0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
147d0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
147e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
147f0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
14800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
14810 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
14820 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
14830 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
14840 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
14850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14860 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
14870 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14880 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
14890 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
148a0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
148b0 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
148c0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
148d0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
148e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
148f0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
14900 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14910 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
14920 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
14930 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
14940 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
14950 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
14960 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
14970 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
14980 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
14990 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
149a0 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
149b0 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
149c0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
149d0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
149e0 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
149f0 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
14a00 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
14a10 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
14a20 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
14a30 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
14a40 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14a50 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
14a60 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
14a70 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
14a80 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14a90 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
14aa0 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
14ab0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
14ac0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
14ad0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
14ae0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
14af0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14b00 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
14b10 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
14b20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14b30 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
14b40 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
14b50 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
14b60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14b70 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
14b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14b90 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
14ba0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14bb0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14bc0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
14bd0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
14be0 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
14bf0 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f  e default size o
14c00 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
14c10 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61  ry on each [data
14c20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14c30 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
14c40 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
14c50 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
14c60 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
14c70 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
14c80 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
14c90 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
14ca0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
14cb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14cc0 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45  ion.)^  ^(SQLITE
14cd0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14ce0 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69  E.** sets the <i
14cf0 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
14d00 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
14d10 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
14d20 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
14d30 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74  option to [sqlit
14d40 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
14d50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
14d60 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
14d70 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
14d80 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
14d90 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
14da0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
14db0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14dc0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14dd0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14de0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14df0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14e00 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
14e10 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14e20 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14e30 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
14e40 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14e50 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14e60 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
14e70 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a  bject specifies.
14e80 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ** the interface
14e90 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
14ea0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
14eb0 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51  tation.)^.** ^SQ
14ec0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
14ed0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
14ee0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14ef0 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  2] object.</dd>.
14f00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14f10 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14f20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14f30 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
14f40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14f50 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14f60 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69  _GETPCACHE2 opti
14f70 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14f80 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14f90 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
14fa0 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14fb0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14fc0 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
14fd0 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68   copies of.** th
14fe0 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63  e current page c
14ff0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
15000 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
15010 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
15020 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15030 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
15040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
15050 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
15060 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15070 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
15080 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
15090 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
150a0 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
150b0 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
150c0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
150d0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
150e0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
150f0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
15100 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
15110 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
15120 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
15130 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
15140 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
15150 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
15160 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
15170 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
15180 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
15190 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
151a0 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
151b0 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
151c0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
151d0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
151e0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
151f0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
15200 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
15210 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
15220 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
15230 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15240 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
15250 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
15260 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
15270 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
15280 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
15290 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
152a0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
152b0 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
152c0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
152d0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
152e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
152f0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
15300 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
15310 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
15320 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15330 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
15340 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
15350 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
15360 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
15370 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
15380 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
15390 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
153a0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
153b0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
153c0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
153d0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
153e0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
153f0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
15400 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
15410 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
15420 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
15430 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
15440 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
15450 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
15460 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
15470 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
15480 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
15490 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
154a0 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
154b0 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
154c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
154d0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
154e0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
154f0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
15500 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15510 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
15520 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
15530 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  dd>^(The SQLITE_
15540 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f  CONFIG_URI optio
15550 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15560 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
15570 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e  e int..** If non
15580 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20  -zero, then URI 
15590 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
155a0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
155b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
155c0 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  s zero,.** then 
155d0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
155e0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
155f0 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
15600 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
15610 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c  y.** enabled, al
15620 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73  l filenames pass
15630 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
15640 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
15650 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20  _open_v2()],.** 
15660 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
15670 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
15680 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
15690 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
156a0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
156b0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
156c0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
156d0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
156e0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
156f0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
15700 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
15710 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
15720 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
15730 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
15740 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
15750 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
15760 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
15770 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
15780 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
15790 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
157a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
157b0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
157c0 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
157d0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
157e0 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
157f0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
15800 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
15810 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
15820 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
15830 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
15840 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
15850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15860 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
15870 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
15880 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
15890 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
158a0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
158b0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
158c0 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69  _INDEX_SCAN opti
158d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
158e0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67  e integer.** arg
158f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
15900 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
15910 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
15920 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
15930 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65  sable.** the use
15940 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
15950 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
15960 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
15970 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
15980 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
15990 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
159a0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
159b0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
159c0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
159d0 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
159e0 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
159f0 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
15a00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15a10 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
15a20 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
15a30 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
15a40 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
15a50 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
15a60 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
15a70 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
15a80 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
15a90 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
15aa0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
15ab0 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
15ac0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
15ad0 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
15ae0 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
15af0 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
15b00 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
15b10 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
15b20 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
15b30 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
15b40 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
15b50 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
15b60 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
15b70 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
15b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15b90 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
15ba0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15bb0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15bc0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
15bd0 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
15be0 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
15bf0 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
15c00 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
15c10 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
15c20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
15c30 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
15c40 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
15c50 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
15c60 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
15c70 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
15c80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15c90 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
15ca0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15cb0 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
15cc0 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
15cd0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
15ce0 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
15cf0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
15d00 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
15d10 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
15d20 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
15d30 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
15d40 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
15d50 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
15d60 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
15d70 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
15d80 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
15d90 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
15da0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
15db0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
15dc0 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
15dd0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
15de0 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
15df0 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
15e00 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
15e10 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
15e20 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
15e30 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
15e40 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
15e50 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15e60 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
15e70 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
15e80 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
15e90 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
15ea0 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
15eb0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
15ec0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
15ed0 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
15ee0 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
15ef0 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
15f00 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
15f10 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
15f20 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
15f30 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
15f40 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
15f50 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
15f60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
15f70 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
15f80 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
15f90 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
15fa0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
15fb0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
15fc0 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
15fd0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
15fe0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
15ff0 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
16000 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
16010 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
16020 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
16030 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
16040 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
16050 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16060 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
16070 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
16080 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
16090 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
160a0 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
160b0 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
160c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
160d0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
160e0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
160f0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16100 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
16110 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16120 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
16130 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
16140 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
16150 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
16160 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
16170 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
16180 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
16190 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
161a0 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
161b0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
161c0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
161d0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
161e0 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
161f0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
16200 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
16210 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
16220 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
16230 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
16240 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
16250 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
16260 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
16270 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
16280 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
16290 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
162a0 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69  ze.** will be si
162b0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
162c0 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f   if necessary so
162d0 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
162e0 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  t exceed the.** 
162f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
16300 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
16310 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
16320 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
16330 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
16340 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
16350 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
16360 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
16370 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
16380 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
16390 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
163a0 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
163b0 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
163c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
163d0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
163e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
163f0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16400 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
16410 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16420 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
16430 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
16440 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
16450 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
16460 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69  d for Windows wi
16470 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
16480 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
16490 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
164a0 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51  .** defined. ^SQ
164b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
164c0 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
164d0 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
164e0 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
164f0 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
16500 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
16510 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
16520 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b  ed heap..**.** [
16530 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
16540 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a  CACHE_HDRSZ]].**
16550 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16560 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a  IG_PCACHE_HDRSZ.
16570 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
16580 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16590 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _HDRSZ option ta
165a0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
165b0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
165c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
165d0 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77  an integer and w
165e0 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20  rites into that 
165f0 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62  integer the numb
16600 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62  er of extra.** b
16610 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65  ytes per page re
16620 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20  quired for each 
16630 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f  page in [SQLITE_
16640 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
16650 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74  ]..** The amount
16660 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20   of extra space 
16670 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61  required can cha
16680 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  nge depending on
16690 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a   the compiler,.*
166a0 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72  * target platfor
166b0 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65  m, and SQLite ve
166c0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rsion..**.** [[S
166d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
166e0 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
166f0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a  TE_CONFIG_PMASZ.
16700 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
16710 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
16720 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
16730 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
16740 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75  which.** is an u
16750 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
16760 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69  and sets the "Mi
16770 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20  nimum PMA Size" 
16780 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72  for the multithr
16790 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20  eaded.** sorter 
167a0 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  to that integer.
167b0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69    The default mi
167c0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69  nimum PMA Size i
167d0 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  s set by the.** 
167e0 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50  [SQLITE_SORTER_P
167f0 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  MASZ] compile-ti
16800 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20  me option.  New 
16810 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e  threads are laun
16820 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20  ched.** to help 
16830 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74  with sort operat
16840 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74  ions when multit
16850 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a  hreaded sorting.
16860 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75  ** is enabled (u
16870 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  sing the [PRAGMA
16880 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e   threads] comman
16890 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e  d) and the amoun
168a0 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20  t of content.** 
168b0 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63  to be sorted exc
168c0 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69  eeds the page si
168d0 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e  ze times the min
168e0 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  imum of the.** [
168f0 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a  PRAGMA cache_siz
16900 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74  e] setting and t
16910 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  his value..**.**
16920 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16930 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
16940 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
16950 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
16960 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68  SPILL.** <dd>^Th
16970 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16980 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f  STMTJRNL_SPILL o
16990 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
169a0 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
169b0 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20  hich.** becomes 
169c0 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a  the [statement j
169d0 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f  ournal] spill-to
169e0 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e  -disk threshold.
169f0 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74    .** [Statement
16a00 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68   journals] are h
16a10 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e  eld in memory un
16a20 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28  til their size (
16a30 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63  in bytes).** exc
16a40 65 65 64 73 20 74 68 69 73 20 74 68 72 65 73 68  eeds this thresh
16a50 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f  old, at which po
16a60 69 6e 74 20 74 68 65 79 20 61 72 65 20 77 72 69  int they are wri
16a70 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a  tten to disk..**
16a80 20 4f 72 20 69 66 20 74 68 65 20 74 68 72 65 73   Or if the thres
16a90 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74  hold is -1, stat
16aa0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61  ement journals a
16ab0 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a  re always held.*
16ac0 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e  * exclusively in
16ad0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63   memory..** Sinc
16ae0 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74  e many statement
16af0 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20   journals never 
16b00 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65  become large, se
16b10 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a  tting the spill.
16b20 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20  ** threshold to 
16b30 61 20 76 61 6c 75 65 20 73 75 63 68 20 61 73 20  a value such as 
16b40 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c  64KiB can greatl
16b50 79 20 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f  y reduce the amo
16b60 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65  unt of.** I/O re
16b70 71 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72  quired to suppor
16b80 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c  t statement roll
16b90 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66  back..** The def
16ba0 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
16bb0 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 63  his setting is c
16bc0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65  ontrolled by the
16bd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54  .** [SQLITE_STMT
16be0 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70  JRNL_SPILL] comp
16bf0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
16c00 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
16c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16c20 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
16c30 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
16c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16c50 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
16c60 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
16c70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16c80 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
16c90 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
16ca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16cb0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
16cc0 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
16cd0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16cf0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
16d00 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
16d10 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
16d20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16d30 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
16d40 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
16d50 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16d60 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16d80 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
16d90 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16da0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16db0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
16dc0 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
16dd0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
16de0 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
16df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e00 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
16e10 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
16e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e30 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
16e40 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
16e50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16e60 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16e70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16e80 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
16e90 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
16ea0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
16eb0 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
16ec0 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
16ed0 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
16ee0 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
16ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f00 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
16f10 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
16f20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16f30 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16f40 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
16f50 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
16f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16f70 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
16f80 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16f90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16fa0 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
16fb0 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
16fc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16fd0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
16fe0 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
16ff0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
17000 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17010 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
17020 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
17030 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
17040 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17050 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
17060 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
17070 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
17080 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17090 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
170a0 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
170b0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
170c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
170d0 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
170e0 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
170f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17100 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
17110 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
17120 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
17130 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
17140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17150 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17160 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
17170 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
17180 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17190 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
171a0 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
171b0 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
171c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
171d0 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
171e0 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
171f0 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
17200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17210 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
17220 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f  SPILL      26  /
17230 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a  * int nByte */..
17240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17250 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
17260 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
17270 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
17280 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
17290 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
172a0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
172b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
172c0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
172d0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
172e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
172f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
17300 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
17310 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
17320 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17330 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
17340 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17350 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
17360 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
17370 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17380 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
17390 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
173a0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
173b0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
173c0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
173d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
173e0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
173f0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
17400 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
17410 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17420 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
17430 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
17440 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
17450 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
17460 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
17470 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
17480 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
17490 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
174a0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
174b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
174c0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
174d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
174e0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
174f0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17500 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
17510 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
17520 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
17530 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
17540 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
17550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17560 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
17570 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
17580 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
17590 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
175a0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
175b0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
175c0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
175d0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
175e0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
175f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
17600 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
17610 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17620 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
17630 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
17640 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
17650 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
17660 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
17670 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
17680 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
17690 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
176a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
176b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
176c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
176d0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
176e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
176f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
17700 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
17710 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
17720 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
17730 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
17740 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
17750 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
17760 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
17770 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
17780 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
17790 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
177a0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
177b0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
177c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
177d0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
177e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
177f0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
17800 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
17810 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
17820 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
17830 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
17840 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
17850 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
17860 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
17870 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
17880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17890 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
178a0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
178b0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
178c0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
178d0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
178e0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
178f0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
17900 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
17910 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
17920 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
17930 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
17940 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17950 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
17960 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
17970 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
17980 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
17990 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
179a0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
179b0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
179c0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
179d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
179e0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
179f0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
17a00 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
17a10 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
17a20 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
17a30 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
17a40 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17a50 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
17a60 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
17a70 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
17a80 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
17a90 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
17aa0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
17ab0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
17ac0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
17ad0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
17ae0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
17af0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
17b00 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
17b10 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
17b20 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
17b30 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
17b40 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
17b50 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
17b60 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
17b70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
17b80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
17b90 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
17ba0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
17bb0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
17bc0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
17bd0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
17be0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
17bf0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17c00 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17c10 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17c20 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17c30 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17c40 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17c50 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
17c60 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
17c70 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
17c80 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
17c90 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
17ca0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17cb0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17cc0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17cd0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
17ce0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
17cf0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
17d00 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
17d10 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
17d20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
17d30 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
17d40 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
17d50 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
17d60 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
17d70 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
17d80 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
17d90 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
17da0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
17db0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17dc0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
17dd0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
17de0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
17df0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
17e00 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
17e10 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
17e20 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
17e30 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
17e40 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
17e50 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17e60 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
17e70 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
17e80 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
17e90 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
17ea0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
17eb0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
17ec0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17ed0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
17ee0 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a  _TOKENIZER</dt>.
17ef0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
17f00 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
17f10 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17f20 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65  e the two-argume
17f30 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  nt.** version of
17f40 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e   the [fts3_token
17f50 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  izer()] function
17f60 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f   which is part o
17f70 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20  f the.** [FTS3] 
17f80 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68  full-text search
17f90 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f   engine extensio
17fa0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  n..** There shou
17fb0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17fc0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17fd0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17fe0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17ff0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
18000 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74  o disable fts3_t
18010 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a  okenizer() or.**
18020 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
18030 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
18040 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65  er() or negative
18050 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
18060 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
18070 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
18080 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18090 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
180a0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
180b0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
180c0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
180d0 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f  te whether fts3_
180e0 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73  tokenizer is dis
180f0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
18100 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
18110 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18120 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18130 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
18140 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
18150 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18160 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18170 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18180 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18190 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
181a0 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
181b0 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ON</dt>.** <dd> 
181c0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
181d0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
181e0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73  r disable the [s
181f0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18200 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65  nsion()].** inte
18210 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e  rface independen
18220 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64  tly of the [load
18230 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51  _extension()] SQ
18240 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  L function..** T
18250 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
18260 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
18270 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73  n()] API enables
18280 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74   or disables bot
18290 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b  h the.** C-API [
182a0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
182b0 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68  ension()] and th
182c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b  e SQL function [
182d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
182e0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
182f0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
18300 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
18310 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73  ** When the firs
18320 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
18330 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
18340 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65  1, then only the
18350 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61   C-API is.** ena
18360 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  bled and the SQL
18370 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e   function remain
18380 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20  s disabled.  If 
18390 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
183a0 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e  nt to.** this in
183b0 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68  terface is 0, th
183c0 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50  en both the C-AP
183d0 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  I and the SQL fu
183e0 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62  nction are disab
183f0 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  led..** If the f
18400 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18410 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61   -1, then no cha
18420 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f  nges are made to
18430 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72   state of either
18440 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72   the.** C-API or
18450 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
18460 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  n..** The second
18470 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
18480 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
18490 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
184a0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
184b0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
184c0 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74  e whether [sqlit
184d0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
184e0 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  n()] interface.*
184f0 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  * is disabled or
18500 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69   enabled followi
18510 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
18520 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18530 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20  ter may.** be a 
18540 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
18550 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18560 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
18570 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
18580 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
18590 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
185a0 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c  NFIG_MAINDBNAME<
185b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
185c0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
185d0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
185e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69  name of the "mai
185f0 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73  n" database.** s
18600 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c  chema.  ^The sol
18610 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
18620 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e  pointer to a con
18630 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e  stant UTF8 strin
18640 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  g.** which will 
18650 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73  become the new s
18660 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c  chema name in pl
18670 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20  ace of "main".  
18680 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20  ^SQLite.** does 
18690 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  not make a copy 
186a0 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20  of the new main 
186b0 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69  schema name stri
186c0 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69  ng, so the appli
186d0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
186e0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
186f0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
18700 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49  nto this DBCONFI
18710 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68  G option is unch
18720 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61  anged.** until a
18730 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73  fter the databas
18740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
18750 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ses..** </dd>.**
18760 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
18770 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
18780 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
18790 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
187a0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
187b0 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
187c0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
187d0 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
187e0 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
187f0 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
18800 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
18810 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
18820 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
18830 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
18840 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
18850 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
18860 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
18870 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
18880 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
18890 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
188a0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
188b0 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
188c0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
188d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
188e0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
188f0 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
18900 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e  s an integer - n
18910 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  on-zero to disab
18920 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
18930 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
18940 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
18950 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
18960 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
18970 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
18980 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
18990 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
189a0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
189b0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
189c0 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
189d0 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
189e0 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
189f0 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
18a00 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
18a10 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
18a20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
18a30 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
18a40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
18a50 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20  INDBNAME        
18a60 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73      1000 /* cons
18a70 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69  t char* */.#defi
18a80 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18a90 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
18aa0 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a           1001 /*
18ab0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
18ac0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18ad0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18ae0 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20  _FKEY           
18af0 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1002 /* int int*
18b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18b10 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18b20 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  LE_TRIGGER      
18b30 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e    1003 /* int in
18b40 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18b50 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18b60 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49  ABLE_FTS3_TOKENI
18b70 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20  ZER 1004 /* int 
18b80 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18b90 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18ba0 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
18bb0 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e  NSION 1005 /* in
18bc0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
18bd0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18be0 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f  G_NO_CKPT_ON_CLO
18bf0 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20  SE      1006 /* 
18c00 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
18c10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
18c20 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
18c30 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
18c40 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
18c50 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
18c60 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
18c70 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
18c80 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
18c90 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
18ca0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
18cb0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
18cc0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
18cd0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
18ce0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
18cf0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
18d00 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
18d10 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
18d20 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
18d30 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
18d40 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
18d50 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
18d60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18d70 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
18d80 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
18d90 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
18da0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
18db0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
18dc0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
18dd0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
18de0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
18df0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
18e00 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
18e10 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
18e20 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
18e30 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
18e40 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
18e50 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
18e60 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
18e70 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
18e80 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
18e90 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
18ea0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
18eb0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
18ec0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
18ed0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
18ee0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
18ef0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
18f00 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
18f10 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
18f20 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
18f30 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
18f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18f50 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18f60 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
18f70 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  ce usually retur
18f80 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
18f90 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  f.** the most re
18fa0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
18fb0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
18fc0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
18fd0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
18fe0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
18ff0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73  nnection D. ^Ins
19000 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
19010 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
19020 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f   are not.** reco
19030 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63  rded. ^If no suc
19040 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
19050 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
19060 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63  les have ever oc
19070 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68  curred .** on th
19080 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19090 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71  ction D, then sq
190a0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
190b0 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
190c0 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a  ns .** zero..**.
190d0 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65  ** As well as be
190e0 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69  ing set automati
190f0 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72  cally as rows ar
19100 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  e inserted into 
19110 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
19120 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
19130 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
19140 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73  unction may be s
19150 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79  et explicitly by
19160 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
19170 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19180 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  id()].**.** Some
19190 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
191a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
191b0 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69  ay INSERT rows i
191c0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
191d0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63   as.** part of c
191e0 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e  ommitting a tran
191f0 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f  saction (e.g. to
19200 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75   flush data accu
19210 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72  mulated in memor
19220 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49  y.** to disk). I
19230 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73  n this case subs
19240 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
19250 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
19260 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a  turn the rowid.*
19270 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
19280 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c  h these internal
19290 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f   INSERT operatio
192a0 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20  ns, which leads 
192b0 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69  to .** unintuiti
192c0 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74  ve results. Virt
192d0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
192e0 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64  entations that d
192f0 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64  o write to rowid
19300 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68  .** tables in th
19310 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64  is way can avoid
19320 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79   this problem by
19330 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f   restoring the o
19340 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69  riginal .** rowi
19350 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73  d value using [s
19360 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
19370 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
19380 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
19390 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20   .** control to 
193a0 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20  the user..**.** 
193b0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
193c0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
193d0 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68   trigger then th
193e0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
193f0 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b  .** return the [
19400 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
19410 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f  serted row as lo
19420 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
19430 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67  r is .** running
19440 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67  . Once the trigg
19450 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c  er program ends,
19460 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19470 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
19480 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
19490 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
194a0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
194b0 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a  r was fired.)^.*
194c0 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
194d0 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
194e0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
194f0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
19500 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
19510 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
19520 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
19530 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19540 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
19550 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
19560 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
19570 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
19580 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
19590 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
195a0 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
195b0 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
195c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
195d0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
195e0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
195f0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
19600 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
19610 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
19620 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
19630 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
19640 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
19650 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
19660 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
19670 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
19680 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
19690 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
196a0 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
196b0 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
196c0 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
196d0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
196e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
196f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
19700 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
19710 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
19720 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
19730 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
19740 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
19750 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
19760 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
19770 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
19780 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
19790 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
197a0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
197b0 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
197c0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
197d0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
197e0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
197f0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
19800 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
19810 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
19820 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
19830 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
19840 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
19850 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19860 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
19870 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
19880 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
19890 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
198a0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
198b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
198c0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
198d0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
198e0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
198f0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
19900 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
19910 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
19920 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
19930 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
19940 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
19950 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19960 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
19970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
19980 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65  et the Last Inse
19990 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a  rt Rowid value..
199a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
199b0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
199c0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
199d0 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29  sert_rowid(D, R)
199e0 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74   method allows t
199f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
19a00 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c  o.** set the val
19a10 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63  ue returned by c
19a20 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c  alling sqlite3_l
19a30 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19a40 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74  (D) to R .** wit
19a50 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61  hout inserting a
19a60 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61   row into the da
19a70 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20  tabase..*/.void 
19a80 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
19a90 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
19aa0 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69  lite3*,sqlite3_i
19ab0 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
19ac0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
19ad0 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
19ae0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
19af0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
19b00 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
19b10 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
19b20 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
19b30 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
19b40 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
19b50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
19b60 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
19b70 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
19b80 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
19b90 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
19ba0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
19bb0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
19bc0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
19bd0 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
19be0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
19bf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
19c00 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
19c10 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
19c20 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
19c30 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
19c40 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
19c50 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
19c60 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19c70 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
19c80 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
19c90 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
19ca0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
19cb0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
19cc0 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
19cd0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
19ce0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
19cf0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
19d00 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
19d10 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
19d20 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
19d30 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
19d40 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
19d50 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
19d60 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
19d70 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
19d80 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
19d90 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
19da0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
19db0 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
19dc0 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
19dd0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
19de0 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
19df0 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
19e00 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
19e10 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
19e20 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
19e30 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
19e40 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
19e50 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
19e60 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
19e70 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19e80 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
19e90 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
19ea0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19eb0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
19ec0 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
19ed0 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
19ee0 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
19ef0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
19f00 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
19f10 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
19f20 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
19f30 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19f40 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
19f50 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
19f60 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
19f70 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
19f80 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
19f90 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
19fa0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
19fb0 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
19fc0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
19fd0 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
19fe0 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
19ff0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
1a000 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
1a010 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
1a020 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
1a030 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
1a040 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
1a050 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
1a060 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
1a070 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
1a080 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
1a090 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a0a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1a0b0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1a0c0 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
1a0d0 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
1a0e0 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
1a0f0 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
1a100 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
1a110 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
1a120 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
1a130 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
1a140 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1a150 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
1a160 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
1a170 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
1a180 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
1a190 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
1a1a0 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
1a1b0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
1a1c0 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
1a1d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
1a1e0 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
1a1f0 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
1a200 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1a210 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1a220 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1a230 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
1a240 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
1a250 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
1a260 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
1a270 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
1a280 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
1a290 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
1a2a0 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
1a2b0 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
1a2c0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1a2d0 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
1a2e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a2f0 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
1a300 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1a310 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1a320 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
1a330 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1a340 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1a350 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
1a360 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
1a370 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1a380 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1a390 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
1a3a0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
1a3b0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
1a3c0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1a3d0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1a3e0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1a3f0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1a400 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1a410 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1a420 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1a430 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1a440 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1a450 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1a460 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
1a470 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1a480 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1a490 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
1a4a0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1a4b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a4c0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
1a4d0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1a4e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1a4f0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1a500 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1a510 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
1a520 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
1a530 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
1a540 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
1a550 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
1a560 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
1a570 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
1a580 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
1a590 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a5a0 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
1a5b0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
1a5c0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
1a5d0 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
1a5e0 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
1a5f0 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
1a600 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
1a610 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
1a620 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
1a630 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1a640 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1a650 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
1a660 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
1a670 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
1a680 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
1a690 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
1a6a0 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
1a6b0 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
1a6c0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
1a6d0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1a6e0 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
1a6f0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
1a700 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1a710 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
1a720 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
1a730 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
1a740 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
1a750 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1a760 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1a770 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1a780 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1a790 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
1a7a0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
1a7b0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1a7c0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1a7d0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1a7e0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1a7f0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1a800 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1a810 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1a820 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1a830 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1a840 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1a850 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1a860 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1a870 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
1a880 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a890 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1a8a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1a8b0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
1a8c0 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20  unning Query.** 
1a8d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a8e0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1a8f0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
1a900 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
1a910 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
1a920 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
1a930 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
1a940 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
1a950 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
1a960 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
1a970 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
1a980 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
1a990 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
1a9a0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
1a9b0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
1a9c0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
1a9d0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
1a9e0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
1a9f0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
1aa00 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
1aa10 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1aa20 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
1aa30 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
1aa40 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
1aa50 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
1aa60 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
1aa70 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
1aa80 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
1aa90 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
1aaa0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1aab0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1aac0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
1aad0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
1aae0 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
1aaf0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ab00 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
1ab10 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
1ab20 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
1ab30 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
1ab40 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
1ab50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
1ab60 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
1ab70 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
1ab80 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
1ab90 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
1aba0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
1abb0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
1abc0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
1abd0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
1abe0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
1abf0 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
1ac00 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1ac10 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
1ac20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
1ac30 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
1ac40 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
1ac50 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1ac60 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
1ac70 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
1ac80 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
1ac90 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
1aca0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
1acb0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
1acc0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
1acd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ace0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
1acf0 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
1ad00 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
1ad10 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
1ad20 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
1ad30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ad40 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
1ad50 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
1ad60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1ad70 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1ad80 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1ad90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1ada0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
1adb0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
1adc0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
1add0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
1ade0 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
1adf0 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
1ae00 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
1ae10 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1ae20 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
1ae30 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1ae40 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1ae50 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
1ae60 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1ae70 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
1ae80 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
1ae90 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
1aea0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1aeb0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
1aec0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
1aed0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
1aee0 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
1aef0 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
1af00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1af10 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
1af20 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
1af30 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1af40 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1af50 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1af60 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1af70 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
1af80 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
1af90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
1afa0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
1afb0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1afc0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
1afd0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
1afe0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
1aff0 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
1b000 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
1b010 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1b020 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
1b030 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
1b040 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
1b050 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
1b060 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
1b070 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
1b080 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
1b090 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
1b0a0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
1b0b0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
1b0c0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
1b0d0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1b0e0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
1b0f0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
1b100 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
1b110 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
1b120 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
1b130 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
1b140 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1b150 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
1b160 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
1b170 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
1b180 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1b190 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
1b1a0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
1b1b0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
1b1c0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
1b1d0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
1b1e0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
1b1f0 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
1b200 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
1b210 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
1b220 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
1b230 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
1b240 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
1b250 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
1b260 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
1b270 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
1b280 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
1b290 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
1b2a0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
1b2b0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
1b2c0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
1b2d0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
1b2e0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
1b2f0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
1b300 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
1b310 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
1b320 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
1b330 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
1b340 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
1b350 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
1b360 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1b370 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
1b380 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
1b390 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
1b3a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1b3b0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
1b3c0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
1b3d0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
1b3e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
1b3f0 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
1b400 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
1b410 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
1b420 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
1b430 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
1b440 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
1b450 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
1b460 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
1b470 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
1b480 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
1b490 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
1b4a0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b4b0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
1b4c0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
1b4d0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
1b4e0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
1b4f0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b500 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
1b510 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
1b520 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
1b530 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1b540 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1b550 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
1b560 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
1b570 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1b580 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
1b590 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
1b5a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
1b5b0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1b5c0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
1b5d0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1b5e0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
1b5f0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
1b600 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1b610 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
1b620 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1b630 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1b640 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
1b650 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1b660 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1b670 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
1b680 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
1b690 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b6a0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
1b6b0 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
1b6c0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
1b6d0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
1b6e0 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
1b6f0 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52  Errors.** KEYWOR
1b700 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65  DS: {busy-handle
1b710 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73  r callback} {bus
1b720 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45  y handler}.** ME
1b730 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1b740 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b750 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c  _busy_handler(D,
1b760 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74  X,P) routine set
1b770 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1b780 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20  ction X.** that 
1b790 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1b7a0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
1b7b0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
1b7c0 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
1b7d0 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61  to access a data
1b7e0 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63  base table assoc
1b7f0 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64  iated with.** [d
1b800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b810 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68  on] D when anoth
1b820 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
1b830 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20  process has the 
1b840 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  table locked..**
1b850 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73   The sqlite3_bus
1b860 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65  y_handler() inte
1b870 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
1b880 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73   implement.** [s
1b890 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1b8a0 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47  out()] and [PRAG
1b8b0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d  MA busy_timeout]
1b8c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b8d0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1b8e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
1b8f0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20  ITE_BUSY].** is 
1b900 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1b910 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
1b920 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
1b930 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
1b940 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
1b950 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
1b960 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
1b970 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1b980 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
1b990 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1b9a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1b9b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1b9c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
1b9d0 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
1b9e0 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
1b9f0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
1ba00 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1ba10 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
1ba20 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
1ba30 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1ba40 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1ba50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
1ba60 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
1ba70 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
1ba80 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65  been invoked pre
1ba90 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20  viously for the 
1baa0 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65  same locking eve
1bab0 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
1bac0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
1bad0 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
1bae0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
1baf0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
1bb00 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
1bb10 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
1bb20 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74  ITE_BUSY] is ret
1bb30 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  urned.** to the 
1bb40 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20  application..** 
1bb50 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
1bb60 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1bb70 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
1bb80 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
1bb90 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  de to access the
1bba0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68   database and th
1bbb0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
1bbc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
1bbd0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
1bbe0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
1bbf0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
1bc00 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
1bc10 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
1bc20 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
1bc30 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
1bc40 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
1bc50 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
1bc60 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
1bc70 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
1bc80 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
1bc90 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
1bca0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
1bcb0 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1bcc0 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f  cation instead o
1bcd0 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a  f invoking the .
1bce0 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  ** busy handler.
1bcf0 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
1bd00 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
1bd10 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
1bd20 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
1bd30 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
1bd40 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
1bd50 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
1bd60 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
1bd70 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
1bd80 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
1bd90 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
1bda0 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
1bdb0 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
1bdc0 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
1bdd0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1bde0 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
1bdf0 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
1be00 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
1be10 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
1be20 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
1be30 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
1be40 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1be50 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
1be60 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
1be70 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
1be80 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1be90 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
1bea0 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
1beb0 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
1bec0 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
1bed0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
1bee0 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
1bef0 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
1bf00 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
1bf10 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
1bf20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
1bf30 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
1bf40 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
1bf50 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1bf60 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
1bf70 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1bf80 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1bf90 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   NULL..**.** ^(T
1bfa0 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1bfb0 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1bfc0 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
1bfd0 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
1bfe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bff0 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
1c000 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
1c010 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
1c020 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
1c030 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
1c040 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
1c050 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1c060 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74  )].** or evaluat
1c070 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79  ing [PRAGMA busy
1c080 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c  _timeout=N] will
1c090 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62   change the.** b
1c0a0 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20  usy handler and 
1c0b0 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70  thus clear any p
1c0c0 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75  reviously set bu
1c0d0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
1c0e0 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
1c0f0 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
1c100 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
1c110 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
1c120 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1c130 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1c140 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1c150 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72  ndler.  In other
1c160 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62   words,.** the b
1c170 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e  usy handler is n
1c180 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41  ot reentrant.  A
1c190 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
1c1a0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
1c1b0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
1c1c0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
1c1d0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
1c1e0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
1c1f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1c200 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
1c210 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
1c220 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1c230 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
1c240 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c250 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74  ler(sqlite3*,int
1c260 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76  (*)(void*,int),v
1c270 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1c280 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
1c290 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45  sy Timeout.** ME
1c2a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1c2b0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1c2c0 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1c2d0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1c2e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1c2f0 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1c300 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1c310 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1c320 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1c330 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1c340 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1c350 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1c360 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1c370 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1c380 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1c390 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1c3a0 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1c3b0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1c3c0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1c3d0 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1c3e0 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1c3f0 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1c400 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1c410 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1c420 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1c430 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1c440 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1c450 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1c460 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1c470 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1c480 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1c490 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1c4a0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1c4b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1c4c0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1c4d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c4e0 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1c4f0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1c500 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1c510 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1c520 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1c530 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c540 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1c550 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1c560 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1c570 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1c580 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1c590 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1c5a0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1c5b0 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  out].*/.int sqli
1c5c0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1c5d0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
1c5e0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
1c5f0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
1c600 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
1c610 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
1c620 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1c630 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
1c640 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1c650 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
1c660 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
1c670 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1c680 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
1c690 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
1c6a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
1c6b0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
1c6c0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
1c6d0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
1c6e0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
1c6f0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
1c700 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1c710 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
1c720 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
1c730 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
1c740 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
1c750 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
1c760 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
1c770 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
1c780 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
1c790 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
1c7a0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
1c7b0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
1c7c0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
1c7d0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
1c7e0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
1c7f0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
1c800 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
1c810 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
1c820 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
1c830 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
1c840 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1c850 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
1c860 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c870 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
1c880 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
1c890 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1c8a0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
1c8b0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
1c8c0 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
1c8d0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
1c8e0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
1c8f0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
1c900 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1c910 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
1c920 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
1c930 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
1c940 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
1c950 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
1c960 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
1c970 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
1c980 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
1c990 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
1c9a0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
1c9b0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
1c9c0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1c9d0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
1c9e0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
1c9f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
1ca00 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
1ca10 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1ca20 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
1ca30 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
1ca40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1ca50 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
1ca60 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
1ca70 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
1ca80 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
1ca90 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
1caa0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
1cab0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
1cac0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1cad0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
1cae0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
1caf0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
1cb00 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
1cb10 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
1cb20 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
1cb30 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1cb40 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1cb50 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
1cb60 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
1cb70 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
1cb80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1cb90 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
1cba0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
1cbb0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
1cbc0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
1cbd0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
1cbe0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1cbf0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1cc00 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
1cc10 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
1cc20 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
1cc30 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
1cc40 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
1cc50 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
1cc60 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
1cc70 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
1cc80 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
1cc90 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
1cca0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
1ccb0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
1ccc0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1ccd0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1cce0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
1ccf0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
1cd00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1cd10 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
1cd20 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1cd30 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
1cd40 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1cd50 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
1cd60 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
1cd70 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
1cd80 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
1cd90 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1cda0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
1cdb0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1cdc0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
1cdd0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1cde0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
1cdf0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1ce00 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1ce10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
1ce20 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
1ce30 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
1ce40 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
1ce50 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
1ce60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1ce70 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
1ce80 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
1ce90 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
1cea0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
1ceb0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
1cec0 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
1ced0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
1cee0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
1cef0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
1cf00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1cf10 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1cf20 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
1cf30 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
1cf40 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
1cf50 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
1cf60 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
1cf70 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
1cf80 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
1cf90 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
1cfa0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
1cfb0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
1cfc0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
1cfd0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1cfe0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
1cff0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
1d000 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
1d010 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
1d020 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
1d030 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
1d040 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
1d050 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
1d060 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1d070 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
1d080 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
1d090 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
1d0a0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
1d0b0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1d0c0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
1d0d0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
1d0e0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
1d0f0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
1d100 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
1d110 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d120 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
1d130 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
1d140 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
1d150 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
1d160 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
1d170 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
1d180 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
1d190 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
1d1a0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
1d1b0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
1d1c0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
1d1d0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
1d1e0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
1d1f0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
1d200 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
1d210 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
1d220 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
1d230 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1d240 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
1d250 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1d260 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
1d270 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d280 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1d290 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1d2a0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1d2b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1d2c0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1d2d0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1d2e0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1d2f0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1d300 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1d310 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1d320 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1d330 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1d340 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1d350 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1d360 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1d370 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1d380 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1d390 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1d3a0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1d3b0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1d3c0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1d3d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1d3e0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1d3f0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1d400 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1d410 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1d420 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1d430 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1d440 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1d450 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1d460 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1d470 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1d480 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1d490 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65   library..** The
1d4a0 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65  se routines unde
1d4b0 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74  rstand most of t
1d4c0 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f  he common K&R fo
1d4d0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1d4e0 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61  ,.** plus some a
1d4f0 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74  dditional non-st
1d500 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20  andard formats, 
1d510 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a  detailed below..
1d520 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d  ** Note that som
1d530 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62  e of the more ob
1d540 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67  scure formatting
1d550 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65   options from re
1d560 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72  cent.** C-librar
1d570 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20  y standards are 
1d580 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69  omitted from thi
1d590 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1d5a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d5b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
1d5c0 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
1d5d0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
1d5e0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
1d5f0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
1d600 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1d610 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d620 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
1d630 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
1d640 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
1d650 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
1d660 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
1d670 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
1d680 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
1d690 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
1d6a0 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
1d6b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
1d6c0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1d6d0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
1d6e0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
1d6f0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
1d700 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1d710 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
1d720 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
1d730 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
1d740 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
1d750 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1d760 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
1d770 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
1d780 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
1d790 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
1d7a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
1d7b0 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
1d7c0 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
1d7d0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
1d7e0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
1d7f0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
1d800 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
1d810 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
1d820 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
1d830 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
1d840 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
1d850 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
1d860 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
1d870 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
1d880 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1d890 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
1d8a0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
1d8b0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
1d8c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1d8d0 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
1d8e0 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
1d8f0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
1d900 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
1d910 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
1d920 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
1d930 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
1d940 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1d950 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
1d960 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
1d970 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
1d980 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
1d990 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
1d9a0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
1d9b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1d9c0 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
1d9d0 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
1d9e0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
1d9f0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
1da00 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
1da10 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
1da20 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1da30 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
1da40 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
1da50 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
1da60 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
1da70 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1da80 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
1da90 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
1daa0 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
1dab0 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
1dac0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
1dad0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
1dae0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
1daf0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
1db00 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
1db10 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
1db20 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
1db30 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1db40 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
1db50 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
1db60 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1db70 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
1db80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
1db90 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
1dba0 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
1dbb0 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
1dbc0 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
1dbd0 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
1dbe0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
1dbf0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
1dc00 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
1dc10 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1dc20 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
1dc30 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
1dc40 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
1dc50 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22  ", "%w" and "%z"
1dc60 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1dc70 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1dc80 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1dc90 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1dca0 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1dcb0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1dcc0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1dcd0 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1dce0 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1dcf0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1dd00 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1dd10 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1dd20 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1dd30 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1dd40 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1dd50 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1dd60 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1dd70 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1dd80 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1dd90 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1dda0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1ddb0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1ddc0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1ddd0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1dde0 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1ddf0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1de00 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1de10 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1de20 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1de30 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1de40 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1de50 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1de60 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1de70 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1de80 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1de90 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1dea0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1deb0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1dec0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1ded0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1dee0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1def0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1df00 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1df10 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1df20 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1df30 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1df40 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1df50 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1df60 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1df70 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1df80 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1df90 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1dfa0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1dfb0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1dfc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1dfd0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1dfe0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1dff0 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1e000 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1e010 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1e020 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1e030 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1e040 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1e050 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1e060 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1e070 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1e080 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1e090 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e0a0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e0b0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1e0c0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1e0d0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1e0e0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1e0f0 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1e100 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1e110 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1e120 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1e130 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1e140 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1e150 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1e160 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1e170 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1e180 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1e190 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1e1a0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1e1b0 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1e1c0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1e1d0 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1e1e0 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1e1f0 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1e200 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1e210 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1e220 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1e230 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1e240 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1e250 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1e260 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1e270 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1e280 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1e290 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1e2a0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1e2b0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1e2c0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1e2d0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1e2e0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1e2f0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1e300 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1e310 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1e320 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1e330 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1e340 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1e350 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1e360 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1e370 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1e380 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1e390 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1e3a0 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1e3b0 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1e3c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1e3d0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20  *.** ^(The "%w" 
1e3e0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1e3f0 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65  n is like "%q" e
1e400 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78  xcept that it ex
1e410 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63  pects to.** be c
1e420 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20  ontained within 
1e430 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e  double-quotes in
1e440 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20  stead of single 
1e450 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a  quotes, and it.*
1e460 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f  * escapes the do
1e470 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61  uble-quote chara
1e480 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  cter instead of 
1e490 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65  the single-quote
1e4a0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e  .** character.)^
1e4b0 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61    The "%w" forma
1e4c0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1e4d0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66  intended for saf
1e4e0 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a  ely inserting.**
1e4f0 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
1e500 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63  n names into a c
1e510 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73  onstructed SQL s
1e520 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
1e530 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
1e540 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
1e550 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
1e560 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
1e570 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
1e580 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
1e590 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
1e5a0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
1e5b0 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
1e5c0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
1e5d0 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
1e5e0 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
1e5f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1e600 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1e610 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1e620 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1e630 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1e640 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
1e650 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
1e660 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1e670 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
1e680 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1e690 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1e6a0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1e6b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e6c0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1e6d0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1e6e0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1e6f0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1e700 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1e710 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1e720 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1e730 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1e740 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1e750 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1e760 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1e770 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1e780 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1e790 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1e7a0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1e7b0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1e7c0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1e7d0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1e7e0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1e7f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e800 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1e810 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1e820 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1e830 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1e840 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1e850 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1e860 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1e870 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1e880 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1e890 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1e8a0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1e8b0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1e8c0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1e8d0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1e8e0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1e8f0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1e900 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1e910 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1e920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1e930 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1e940 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1e950 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1e960 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1e970 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1e980 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1e990 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1e9a0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1e9b0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1e9c0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1e9d0 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1e9e0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1e9f0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1ea00 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1ea10 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1ea20 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1ea30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1ea40 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1ea50 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1ea60 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1ea70 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1ea80 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1ea90 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1eaa0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1eab0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1eac0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1ead0 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1eae0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1eaf0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1eb00 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1eb10 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1eb20 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1eb30 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1eb40 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1eb50 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1eb60 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1eb70 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1eb80 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1eb90 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1eba0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1ebb0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1ebc0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1ebd0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1ebe0 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1ebf0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1ec00 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1ec10 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1ec20 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1ec30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1ec40 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1ec50 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1ec60 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1ec70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1ec80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ec90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1eca0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1ecb0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1ecc0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1ecd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1ece0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1ecf0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1ed00 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1ed10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1ed20 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1ed30 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1ed40 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1ed50 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1ed60 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1ed70 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1ed80 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1ed90 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1eda0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1edb0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1edc0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1edd0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1ede0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1edf0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1ee00 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1ee10 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1ee20 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1ee30 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1ee40 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1ee50 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1ee60 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1ee70 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1ee80 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1ee90 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1eea0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1eeb0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1eec0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1eed0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1eee0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1eef0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1ef00 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1ef10 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1ef20 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1ef30 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1ef40 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1ef50 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1ef60 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1ef70 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1ef80 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1ef90 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1efa0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1efb0 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1efc0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1efd0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1efe0 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1eff0 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1f000 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1f010 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1f020 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1f030 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1f040 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1f050 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1f060 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1f070 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1f080 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f090 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1f0a0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1f0b0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1f0c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1f0d0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1f0e0 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1f0f0 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1f100 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1f110 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1f120 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1f130 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f140 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1f150 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1f160 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1f170 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1f180 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1f190 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1f1a0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1f1b0 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1f1c0 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1f1d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1f1e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1f1f0 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1f200 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1f210 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1f220 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1f230 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1f240 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1f250 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1f260 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1f270 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1f280 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1f290 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1f2a0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1f2b0 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1f2c0 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1f2d0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1f2e0 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1f2f0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1f300 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1f310 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1f320 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1f330 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1f340 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1f350 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1f360 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1f370 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1f380 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1f390 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1f3a0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1f3b0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1f3c0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1f3d0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1f3e0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1f3f0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1f400 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1f410 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1f420 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1f430 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1f440 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1f450 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1f460 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1f470 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1f480 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1f490 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1f4a0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1f4b0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1f4c0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1f4d0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1f4e0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1f4f0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1f500 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1f510 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1f520 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1f530 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1f540 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1f550 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1f560 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1f570 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1f580 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1f590 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1f5a0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1f5b0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1f5c0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1f5d0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1f5e0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1f5f0 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1f600 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1f610 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1f620 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1f630 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1f640 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1f650 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1f660 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1f670 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1f680 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1f690 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1f6a0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1f6b0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1f6c0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1f6d0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1f6e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f6f0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1f700 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1f710 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1f720 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1f730 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1f740 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1f750 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1f760 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1f770 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1f780 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1f790 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1f7a0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1f7b0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1f7c0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1f7d0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1f7e0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1f7f0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1f800 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f810 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1f820 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
1f830 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1f840 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
1f850 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73  lite3_malloc64(s
1f860 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1f870 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1f880 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1f890 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1f8a0 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a  _realloc64(void*
1f8b0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
1f8c0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1f8d0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c  free(void*);.sql
1f8e0 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69  ite3_uint64 sqli
1f8f0 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29  te3_msize(void*)
1f900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f910 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1f920 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1f930 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1f940 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1f950 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1f960 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1f970 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1f980 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1f990 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1f9a0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1f9b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1f9c0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1f9d0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1f9e0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1f9f0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1fa00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1fa10 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1fa20 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1fa30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1fa40 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1fa50 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1fa60 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1fa70 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1fa80 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1fa90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1faa0 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1fab0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1fac0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1fad0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1fae0 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1faf0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1fb00 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1fb10 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1fb20 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1fb30 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1fb40 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1fb50 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1fb60 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1fb70 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1fb80 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1fb90 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1fba0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1fbb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1fbc0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1fbd0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1fbe0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1fbf0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1fc00 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1fc10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1fc20 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1fc30 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1fc40 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1fc50 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1fc60 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1fc70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1fc80 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1fc90 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1fca0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1fcb0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1fcc0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1fcd0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1fce0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1fcf0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1fd00 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1fd10 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1fd20 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1fd30 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
1fd40 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1fd50 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1fd60 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
1fd70 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1fd80 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1fd90 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1fda0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1fdb0 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1fdc0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1fdd0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1fde0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1fdf0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1fe00 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1fe10 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1fe20 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1fe30 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1fe40 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1fe50 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1fe60 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1fe70 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1fe80 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1fe90 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1fea0 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1feb0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1fec0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1fed0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1fee0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1fef0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1ff00 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1ff10 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1ff20 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1ff30 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1ff40 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1ff50 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1ff60 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1ff70 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1ff80 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1ff90 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
1ffa0 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
1ffb0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1ffc0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
1ffd0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
1ffe0 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
1fff0 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
20000 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
20010 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
20020 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
20030 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
20040 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
20050 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
20060 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
20070 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
20080 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
20090 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
200a0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
200b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
200c0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
200d0 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
200e0 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
200f0 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
20100 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
20110 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
20120 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
20130 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
20140 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
20150 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
20160 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
20170 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
20180 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
20190 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
201a0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
201b0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
201c0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
201d0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  on Callbacks.** 
201e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
201f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
20200 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
20210 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20220 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
20230 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
20240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
20250 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
20260 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
20270 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
20280 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20290 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
202a0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
202b0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
202c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
202d0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
202e0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
202f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
20300 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20310 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
20320 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20330 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
20340 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
20350 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
20360 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
20370 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
20380 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
20390 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
203a0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
203b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
203c0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
203d0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
203e0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
203f0 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
20400 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
20410 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
20420 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
20430 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
20440 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
20450 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
20460 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
20470 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
20480 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
20490 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
204a0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
204b0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
204c0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
204d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
204e0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
204f0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
20500 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
20510 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
20520 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
20530 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
20540 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
20550 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
20560 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
20570 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
20580 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
20590 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
205a0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
205b0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
205c0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
205d0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
205e0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
205f0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
20600 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
20610 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
20620 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
20630 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
20640 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
20650 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
20660 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
20670 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20680 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
20690 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
206a0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
206b0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
206c0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
206d0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
206e0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
206f0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
20700 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
20710 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20720 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20730 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
20740 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
20750 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
20760 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
20770 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
20780 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
20790 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
207a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
207b0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
207c0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
207d0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
207e0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
207f0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
20800 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
20810 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
20820 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
20830 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
20840 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
20850 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
20860 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
20870 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
20880 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
20890 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
208a0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
208b0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
208c0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
208d0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
208e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
208f0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
20900 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
20910 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20920 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
20930 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
20940 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
20950 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
20960 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
20970 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
20980 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
20990 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
209a0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
209b0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
209c0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
209d0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
209e0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
209f0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
20a00 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
20a10 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
20a20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
20a30 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
20a40 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
20a50 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
20a60 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
20a70 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
20a80 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
20a90 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
20aa0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
20ab0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
20ac0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
20ad0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
20ae0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
20af0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
20b00 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
20b10 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
20b20 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
20b30 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
20b40 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
20b50 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
20b60 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
20b70 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
20b80 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
20b90 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
20ba0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
20bb0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
20bc0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
20bd0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
20be0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
20bf0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
20c00 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
20c10 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
20c20 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
20c30 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
20c40 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
20c50 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
20c60 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
20c70 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
20c80 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
20c90 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
20ca0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
20cb0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
20cc0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
20cd0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
20ce0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
20cf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
20d00 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
20d10 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
20d20 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
20d30 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
20d40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
20d50 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
20d60 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
20d70 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
20d80 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
20d90 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
20da0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
20db0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
20dc0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
20dd0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
20de0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
20df0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
20e00 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
20e10 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
20e20 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
20e30 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
20e40 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
20e50 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
20e60 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
20e70 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
20e80 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
20e90 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
20ea0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
20eb0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
20ec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20ed0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
20ee0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
20ef0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20f00 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
20f10 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
20f20 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
20f30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20f40 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
20f50 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
20f60 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
20f70 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
20f80 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
20f90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20fa0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
20fb0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
20fc0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
20fd0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20fe0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
20ff0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
21000 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
21010 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
21020 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21030 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
21040 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
21050 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
21060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
21070 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
21080 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
21090 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
210a0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
210b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
210c0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
210d0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
210e0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
210f0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
21100 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
21110 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21120 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
21130 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
21140 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
21150 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
21160 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
21170 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
21180 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
21190 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
211a0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
211b0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
211c0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
211d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
211e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
211f0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
21200 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
21210 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
21220 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
21230 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
21240 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
21250 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
21260 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
21270 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
21280 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
21290 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
212a0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
212b0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
212c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
212d0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
212e0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
212f0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
21300 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
21310 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21320 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
21330 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
21340 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
21350 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
21360 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
21370 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
21380 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
21390 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
213a0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
213b0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
213c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
213d0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
213e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
213f0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
21400 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
21410 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
21420 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
21430 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
21440 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
21450 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
21460 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
21470 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
21480 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
21490 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
214a0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
214b0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
214c0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
214d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
214e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
214f0 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
21500 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f  so used as a [co
21510 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f  nflict resolutio
21520 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72  n mode].** retur
21530 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ned from the [sq
21540 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
21550 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
21560 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
21570 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
21580 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
21590 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
215a0 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
215b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
215c0 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
215d0 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
215e0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
215f0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
21600 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
21610 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
21620 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
21630 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
21640 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
21650 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
21660 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
21670 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
21680 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
21690 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
216a0 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
216b0 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
216c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
216d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
216e0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
216f0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
21700 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
21710 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
21720 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
21730 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
21740 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
21750 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21760 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
21770 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
21780 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
21790 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
217a0 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
217b0 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
217c0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
217d0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
217e0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
217f0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
21800 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
21810 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
21820 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
21830 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
21840 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
21850 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
21860 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
21870 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
21880 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
21890 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
218a0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
218b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
218c0 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
218d0 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
218e0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
218f0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
21900 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
21910 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
21920 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
21930 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
21940 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
21950 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
21960 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
21970 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
21980 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
21990 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
219a0 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
219b0 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
219c0 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
219d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
219e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
219f0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
21a00 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
21a10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21a20 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
21a30 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
21a40 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
21a50 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21a60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21a70 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
21a80 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
21a90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21aa0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21ab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21ac0 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
21ad0 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
21ae0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
21af0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21b00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21b10 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
21b20 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
21b30 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
21b40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21b50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21b60 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
21b70 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
21b80 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
21b90 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21bb0 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
21bc0 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
21bd0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
21be0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21c00 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
21c10 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
21c20 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
21c30 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21c40 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21c50 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
21c60 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
21c70 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
21c80 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21c90 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
21ca0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21cb0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
21cc0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21cd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21ce0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
21cf0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
21d00 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
21d10 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
21d20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21d30 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
21d40 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
21d50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21d60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21d70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21d80 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
21d90 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
21da0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
21db0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21dc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21dd0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
21de0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
21df0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21e00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21e10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21e20 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
21e30 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
21e40 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
21e50 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21e60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21e70 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
21e80 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
21e90 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
21ea0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21eb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21ec0 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
21ed0 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
21ee0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
21ef0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21f00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21f10 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
21f20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
21f30 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
21f40 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21f50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21f60 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
21f70 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
21f80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21f90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21fa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21fb0 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
21fc0 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
21fd0 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
21fe0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
21ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
22000 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
22010 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
22020 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
22030 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
22040 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
22050 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
22060 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
22070 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
22080 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
220a0 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
220b0 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
220c0 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
220d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
220e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
220f0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
22100 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
22110 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
22120 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
22130 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
22140 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
22150 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
22160 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
22170 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22180 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
22190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
221a0 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
221b0 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
221c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
221d0 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
221e0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
221f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
22200 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
22210 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22220 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
22230 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
22240 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
22250 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22260 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22270 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
22280 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
22290 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
222a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
222b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
222c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
222d0 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
222e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
222f0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
22300 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22310 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
22320 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
22330 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22340 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
22350 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22360 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
22370 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
22380 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22390 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
223a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
223b0 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
223c0 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
223d0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
223e0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
223f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22400 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
22410 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
22420 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
22430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22440 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
22450 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c       33   /* NUL
22460 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
22470 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22490 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
224a0 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
224b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
224c0 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  te3.**.** These 
224d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70  routines are dep
224e0 72 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65  recated. Use the
224f0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
22500 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  v2()] interface.
22510 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ** instead of th
22520 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72  e routines descr
22530 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ibed here..**.**
22540 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
22550 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
22560 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
22570 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
22580 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
22590 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
225a0 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
225b0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
225c0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
225d0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
225e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
225f0 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
22600 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
22610 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
22620 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
22630 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
22640 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
22650 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
22660 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
22670 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
22680 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
22690 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
226a0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
226b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
226c0 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
226d0 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
226e0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
226f0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
22700 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
22710 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
22720 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
22730 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
22740 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
22750 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
22760 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
22770 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
22780 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
22790 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
227a0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
227b0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
227c0 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
227d0 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
227e0 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
227f0 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
22800 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
22810 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
22820 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
22830 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
22840 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
22850 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
22860 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
22870 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
22880 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
22890 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
228a0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
228b0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
228c0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
228d0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
228e0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
228f0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
22900 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
22910 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
22920 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
22930 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
22940 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
22950 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
22960 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
22970 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
22980 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
22990 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
229a0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
229b0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
229c0 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
229d0 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
229e0 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
229f0 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
22a00 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
22a10 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
22a20 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
22a30 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
22a40 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
22a50 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
22a60 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
22a70 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
22a80 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
22a90 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
22aa0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
22ab0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
22ac0 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
22ad0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
22ae0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
22af0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
22b00 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
22b10 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
22b20 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  id*);.SQLITE_DEP
22b30 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
22b40 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
22b50 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
22b60 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
22b70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
22b80 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
22b90 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
22ba0 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65  I3REF: SQL Trace
22bb0 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20   Event Codes.** 
22bc0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
22bd0 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65  _TRACE.**.** The
22be0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65  se constants ide
22bf0 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66  ntify classes of
22c00 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e   events that can
22c10 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a   be monitored.**
22c20 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
22c30 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
22c40 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20  tracing logic.  
22c50 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
22c60 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  nt.** to [sqlite
22c70 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73  3_trace_v2()] is
22c80 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e   an OR-ed combin
22c90 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20  ation of one or 
22ca0 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66  more of.** the f
22cb0 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e  ollowing constan
22cc0 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ts.  ^The first 
22cd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
22ce0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
22cf0 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  * is one of the 
22d00 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61  following consta
22d10 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74  nts..**.** New t
22d20 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  racing constants
22d30 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
22d40 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
22d50 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65  ..**.** ^A trace
22d60 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f   callback has fo
22d70 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43  ur arguments: xC
22d80 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
22d90 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
22da0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
22db0 68 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20  he integer type 
22dc0 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20  codes above..** 
22dd0 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
22de0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
22df0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
22e00 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
22e10 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75  e.** fourth argu
22e20 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
22e30 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a  _trace_v2()]..**
22e40 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
22e50 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
22e60 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
22e70 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
22e80 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
22e90 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
22ea0 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  T]] <dt>SQLITE_T
22eb0 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a  RACE_STMT</dt>.*
22ec0 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
22ed0 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c  _TRACE_STMT call
22ee0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
22ef0 77 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20  when a prepared 
22f00 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72  statement.** fir
22f10 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e  st begins runnin
22f20 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61  g and possibly a
22f30 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75  t other times du
22f40 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63  ring the.** exec
22f50 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65  ution of the pre
22f60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c  pared statement,
22f70 20 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20   such as at the 
22f80 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a  start of each.**
22f90 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
22fa0 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75  ram. ^The P argu
22fb0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
22fc0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65  r to the.** [pre
22fd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22fe0 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e  . ^The X argumen
22ff0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23000 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
23010 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70  .** is the unexp
23020 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f  anded SQL text o
23030 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
23040 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53  tatement or an S
23050 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74  QL comment .** t
23060 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
23070 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  e invocation of 
23080 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65  a trigger.  ^The
23090 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f   callback can co
230a0 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d  mpute.** the sam
230b0 65 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c  e text that woul
230c0 64 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75  d have been retu
230d0 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61  rned by the lega
230e0 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  cy [sqlite3_trac
230f0 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e()].** interfac
23100 65 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58  e by using the X
23110 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58   argument when X
23120 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d   begins with "--
23130 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a  " and invoking.*
23140 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  * [sqlite3_expan
23150 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65  ded_sql(P)] othe
23160 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rwise..**.** [[S
23170 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
23180 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ILE]] <dt>SQLITE
23190 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f  _TRACE_PROFILE</
231a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
231b0 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
231c0 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f  ILE callback pro
231d0 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74  vides approximat
231e0 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  ely the same.** 
231f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69  information as i
23200 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
23210 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  e [sqlite3_profi
23220 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a  le()] callback..
23230 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
23240 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
23250 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
23260 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
23270 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e  the.** X argumen
23280 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34  t points to a 64
23290 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69  -bit integer whi
232a0 63 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61  ch is the estima
232b0 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75  ted of.** the nu
232c0 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  mber of nanoseco
232d0 6e 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70  nd that the prep
232e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74  ared statement t
232f0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e  ook to run..** ^
23300 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  The SQLITE_TRACE
23310 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63  _PROFILE callbac
23320 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
23330 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
23340 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20  finishes..**.** 
23350 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  [[SQLITE_TRACE_R
23360 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OW]] <dt>SQLITE_
23370 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a  TRACE_ROW</dt>.*
23380 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
23390 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62  _TRACE_ROW callb
233a0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
233b0 68 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72  henever a prepar
233c0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
233d0 67 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67  generates a sing
233e0 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74  le row of result
233f0 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  .  .** ^The P ar
23400 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
23410 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70  ter to the [prep
23420 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23430 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67  and the.** X arg
23440 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e  ument is unused.
23450 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
23460 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64  TRACE_CLOSE]] <d
23470 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  t>SQLITE_TRACE_C
23480 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LOSE</dt>.** <dd
23490 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
234a0 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b  E_CLOSE callback
234b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
234c0 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
234d0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
234e0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75  ..** ^The P argu
234f0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
23500 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
23510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
23520 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65  bject.** and the
23530 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75   X argument is u
23540 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  nused..** </dl>.
23550 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23560 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20  E_TRACE_STMT    
23570 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20     0x01.#define 
23580 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
23590 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65  FILE    0x02.#de
235a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
235b0 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30  E_ROW        0x0
235c0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
235d0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20  _TRACE_CLOSE    
235e0 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41    0x08../*.** CA
235f0 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63  PI3REF: SQL Trac
23600 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44  e Hook.** METHOD
23610 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23620 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
23630 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69  ce_v2(D,M,X,P) i
23640 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
23650 72 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62  rs a trace callb
23660 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
23670 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62  X against [datab
23680 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
23690 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74  D, using propert
236a0 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20  y mask M.** and 
236b0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20  context pointer 
236c0 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61  P.  ^If the X ca
236d0 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c  llback is.** NUL
236e0 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61  L or if the M ma
236f0 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  sk is zero, then
23700 20 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61   tracing is disa
23710 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20  bled.  The.** M 
23720 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
23730 62 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f  be the bitwise O
23740 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  R-ed combination
23750 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d   of.** zero or m
23760 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  ore [SQLITE_TRAC
23770 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  E] constants..**
23780 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74  .** ^Each call t
23790 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  o either sqlite3
237a0 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69  _trace() or sqli
237b0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f  te3_trace_v2() o
237c0 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61  verrides .** (ca
237d0 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72  ncels) any prior
237e0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
237f0 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c  3_trace() or sql
23800 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e  ite3_trace_v2().
23810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61  .**.** ^The X ca
23820 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
23830 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f  d whenever any o
23840 66 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65  f the events ide
23850 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d  ntified by .** m
23860 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54  ask M occur.  ^T
23870 68 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72  he integer retur
23880 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65  n value from the
23890 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72   callback is cur
238a0 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65  rently.** ignore
238b0 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d  d, though this m
238c0 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  ay change in fut
238d0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43  ure releases.  C
238e0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65  allback.** imple
238f0 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
23900 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f  d return zero to
23910 20 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63   ensure future c
23920 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
23930 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c  .** ^A trace cal
23940 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
23950 20 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d   with four argum
23960 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54  ents: callback(T
23970 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65  ,C,P,X)..** ^The
23980 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f   T argument is o
23990 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ne of the [SQLIT
239a0 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73  E_TRACE].** cons
239b0 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74  tants to indicat
239c0 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61  e why the callba
239d0 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a  ck was invoked..
239e0 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65  ** ^The C argume
239f0 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  nt is a copy of 
23a00 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
23a10 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e  ter..** The P an
23a20 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72  d X arguments ar
23a30 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65  e pointers whose
23a40 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64   meanings depend
23a50 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   on T..**.** The
23a60 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
23a70 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
23a80 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70   intended to rep
23a90 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a  lace the legacy.
23aa0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
23ab0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
23ac0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  and [sqlite3_pro
23ad0 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66  file()], both of
23ae0 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65   which.** are de
23af0 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74  precated..*/.int
23b00 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
23b10 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  2(.  sqlite3*,. 
23b20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c   unsigned uMask,
23b30 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63  .  int(*xCallbac
23b40 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64  k)(unsigned,void
23b50 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a  *,void*,void*),.
23b60 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a    void *pCtx.);.
23b70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23b80 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
23b90 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
23ba0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
23bb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23bc0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
23bd0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
23be0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
23bf0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
23c00 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
23c10 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
23c20 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
23c30 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
23c40 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
23c50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
23c60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23c70 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
23c80 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
23c90 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
23ca0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
23cb0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
23cc0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
23cd0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
23ce0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
23cf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
23d00 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
23d10 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
23d20 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
23d30 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
23d40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
23d50 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
23d60 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
23d70 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
23d80 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
23d90 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
23da0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
23db0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
23dc0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
23dd0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
23de0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
23df0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
23e00 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
23e10 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
23e20 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
23e30 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
23e40 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23e50 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
23e60 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
23e70 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
23e80 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
23e90 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
23ea0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
23eb0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
23ec0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
23ed0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
23ee0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
23ef0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
23f00 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
23f10 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
23f20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
23f30 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
23f40 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
23f50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
23f60 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
23f70 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
23f80 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
23f90 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
23fa0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
23fb0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
23fc0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
23fd0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
23fe0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
23ff0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
24000 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
24010 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
24020 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
24030 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
24040 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
24050 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24060 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
24070 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
24080 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
24090 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
240a0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
240b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
240c0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
240d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
240e0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
240f0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
24100 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
24110 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
24120 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
24130 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
24140 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
24150 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
24160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24170 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
24180 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
24190 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  tion.** CONSTRUC
241a0 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  TOR: sqlite3.**.
241b0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
241c0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
241d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
241e0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
241f0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
24200 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
24210 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
24220 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
24230 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
24240 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24250 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
24260 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
24270 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
24280 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
24290 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
242a0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
242b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
242c0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
242d0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
242e0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
242f0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
24300 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
24310 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
24320 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
24330 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
24340 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
24350 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
24360 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
24370 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
24380 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
24390 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
243a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
243b0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
243c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
243d0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
243e0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
243f0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
24400 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
24410 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
24420 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
24430 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
24440 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
24450 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
24460 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
24470 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
24480 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
24490 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
244a0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
244b0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
244c0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
244d0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
244e0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
244f0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
24500 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
24510 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77  fault encoding w
24520 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72  ill be UTF-8 for
24530 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74   databases creat
24540 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69  ed using.** sqli
24550 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
24560 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
24570 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65    ^The default e
24580 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61  ncoding for data
24590 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  bases.** created
245a0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f   using sqlite3_o
245b0 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20  pen16() will be 
245c0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
245d0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
245e0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
245f0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
24600 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
24610 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
24620 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
24630 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
24640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24650 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
24660 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
24670 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
24680 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
24690 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
246a0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
246b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
246c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
246d0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
246e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
246f0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
24700 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
24710 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
24720 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
24730 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
24740 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
24750 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
24760 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
24770 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
24780 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
24790 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
247a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
247b0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
247c0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
247d0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
247e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
247f0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
24800 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
24810 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
24820 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
24830 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
24840 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
24850 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
24860 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
24870 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
24880 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
24890 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
248a0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
248b0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
248c0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
248d0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
248e0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
248f0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
24900 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
24910 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
24920 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
24930 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
24940 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
24950 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
24960 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
24970 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
24980 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
24990 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
249a0 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
249b0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
249c0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
249d0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
249e0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
249f0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
24a00 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
24a10 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
24a20 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
24a30 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
24a40 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
24a50 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
24a60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24a70 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
24a80 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
24a90 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
24aa0 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
24ab0 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
24ac0 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
24ad0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
24ae0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
24af0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
24b00 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
24b10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
24b20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
24b30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
24b40 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
24b50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24b60 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
24b70 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
24b80 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
24b90 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
24ba0 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
24bb0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
24bc0 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
24bd0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
24be0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
24bf0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
24c00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
24c10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
24c20 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
24c30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
24c40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
24c50 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
24c60 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
24c70 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
24c80 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
24c90 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
24ca0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
24cb0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
24cc0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
24cd0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
24ce0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
24cf0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
24d00 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
24d10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
24d20 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
24d30 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
24d40 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
24d50 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
24d60 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
24d70 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
24d80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
24d90 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
24da0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
24db0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
24dc0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
24dd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24de0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
24df0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
24e00 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
24e10 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
24e20 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
24e30 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
24e40 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
24e50 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
24e60 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
24e70 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
24e80 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
24e90 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
24ea0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24eb0 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
24ec0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
24ed0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
24ee0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
24ef0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
24f00 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
24f10 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
24f20 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
24f30 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
24f40 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
24f50 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
24f60 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
24f70 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
24f80 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
24f90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24fa0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
24fb0 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
24fc0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
24fd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
24fe0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
24ff0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
25000 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
25010 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
25020 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
25030 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
25040 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
25050 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
25060 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
25070 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
25080 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
25090 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
250a0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
250b0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
250c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
250d0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
250e0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
250f0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
25100 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
25110 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
25120 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
25130 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
25140 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
25150 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
25160 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
25170 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
25180 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
25190 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
251a0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
251b0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
251c0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
251d0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
251e0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
251f0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
25200 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
25210 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25220 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
25230 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
25240 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
25250 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
25260 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
25270 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
25280 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
25290 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
252a0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
252b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
252c0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
252d0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
252e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
252f0 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
25300 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
25310 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
25320 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
25330 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
25340 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
25350 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
25360 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
25370 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
25380 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
25390 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
253a0 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
253b0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
253c0 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
253d0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
253e0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
253f0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
25400 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
25410 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
25420 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
25430 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
25440 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
25450 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
25460 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
25470 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
25480 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
25490 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
254a0 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
254b0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
254c0 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
254d0 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
254e0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
254f0 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
25500 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
25510 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
25520 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
25530 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
25540 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
25550 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
25560 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
25570 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
25580 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
25590 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
255a0 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
255b0 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
255c0 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
255d0 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
255e0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
255f0 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
25600 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
25610 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
25620 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
25630 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
25640 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
25650 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
25660 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
25670 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
25680 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
25690 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
256a0 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
256b0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
256c0 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
256d0 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
256e0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
256f0 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
25700 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
25710 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
25720 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
25730 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
25740 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
25750 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
25760 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
25770 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
25780 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
25790 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
257a0 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
257b0 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
257c0 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
257d0 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
257e0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
257f0 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
25800 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
25810 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
25820 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
25830 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
25840 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e  th. .** ^(On win
25850 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
25860 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
25870 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
25880 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
25890 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
258a0 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20   "C:").)^.**.** 
258b0 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
258c0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
258d0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
258e0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
258f0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
25900 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
25910 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
25920 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
25930 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
25940 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
25950 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
25960 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69  .** SQLite and i
25970 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53  ts built-in [VFS
25980 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68  es] interpret th
25990 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71  e.** following q
259a0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
259b0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
259c0 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
259d0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
259e0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
259f0 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
25a00 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
25a10 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
25a20 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
25a30 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
25a40 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
25a50 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
25a60 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
25a70 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
25a80 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
25a90 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
25aa0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
25ab0 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
25ac0 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
25ad0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
25ae0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
25af0 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
25b00 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
25b10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25b20 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
25b30 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
25b40 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
25b50 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
25b60 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
25b70 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
25b80 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
25b90 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
25ba0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
25bb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
25bc0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
25bd0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
25be0 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
25bf0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
25c00 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
25c10 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
25c20 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
25c30 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
25c40 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
25c50 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
25c60 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
25c70 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
25c80 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
25c90 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
25ca0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
25cb0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
25cc0 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
25cd0 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
25ce0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
25cf0 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
25d00 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
25d10 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
25d20 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
25d30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
25d40 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
25d50 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
25d60 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
25d70 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
25d80 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
25d90 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
25da0 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
25db0 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
25dc0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
25dd0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
25de0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
25df0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
25e00 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
25e10 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
25e20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
25e30 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
25e40 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
25e50 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
25e60 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
25e70 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
25e80 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
25e90 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
25ea0 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
25eb0 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
25ec0 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
25ed0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
25ee0 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
25ef0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
25f00 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
25f10 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
25f20 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
25f30 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
25f40 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
25f50 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
25f60 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
25f70 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
25f80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
25f90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
25fa0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
25fb0 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
25fc0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
25fd0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
25fe0 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
25ff0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
26000 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
26010 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
26020 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
26030 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
26040 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
26050 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
26060 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
26070 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
26080 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
26090 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
260a0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
260b0 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
260c0 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
260d0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
260e0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
260f0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
26100 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
26110 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26120 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
26130 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
26140 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
26150 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
26160 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
26170 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
26180 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
26190 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
261a0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
261b0 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
261c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
261d0 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
261e0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f  .**  <li> <b>pso
261f0 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77  w</b>: ^The psow
26200 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63   parameter indic
26210 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ates whether or 
26220 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  not the.**     [
26230 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
26240 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
26250 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
26260 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
26270 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
26280 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
26290 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
262a0 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  des..**.**  <li>
262b0 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20   <b>nolock</b>: 
262c0 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61  ^The nolock para
262d0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
262e0 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  an query paramet
262f0 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
26300 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20  if set disables 
26310 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20  file locking in 
26320 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
26330 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a   modes.  This.**
26340 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66       is useful f
26350 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64  or accessing a d
26360 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c  atabase on a fil
26370 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65  esystem that doe
26380 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70  s not.**     sup
26390 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43  port locking.  C
263a0 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73  aution:  Databas
263b0 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67  e corruption mig
263c0 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f  ht result if two
263d0 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20  .**     or more 
263e0 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20  processes write 
263f0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
26400 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65  base and any one
26410 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20   of those.**    
26420 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20   processes uses 
26430 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20  nolock=1..**.** 
26440 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62   <li> <b>immutab
26450 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d  le</b>: ^The imm
26460 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72  utable parameter
26470 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
26480 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
26490 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61  eter that indica
264a0 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74  tes that the dat
264b0 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74  abase file is st
264c0 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72  ored on.**     r
264d0 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20  ead-only media. 
264e0 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65   ^When immutable
264f0 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20   is set, SQLite 
26500 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
26510 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
26520 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
26530 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79  changed, even by
26540 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20   a process with 
26550 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72  higher.**     pr
26560 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20  ivilege, and so 
26570 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
26580 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79  opened read-only
26590 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67   and all locking
265a0 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e  .**     and chan
265b0 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ge detection is 
265c0 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69  disabled.  Cauti
265d0 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20  on: Setting the 
265e0 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20  immutable.**    
265f0 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64   property on a d
26600 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61  atabase file tha
26610 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63  t does in fact c
26620 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74  hange can result
26630 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72  .**     in incor
26640 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c  rect query resul
26650 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ts and/or [SQLIT
26660 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72  E_CORRUPT] error
26670 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c  s..**     See al
26680 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  so: [SQLITE_IOCA
26690 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a  P_IMMUTABLE]..**
266a0 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e         .** </ul>
266b0 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
266c0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
266d0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
266e0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
266f0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
26700 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
26710 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
26720 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
26730 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
26740 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
26750 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
26760 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
26770 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
26780 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
26790 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
267a0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
267b0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
267c0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
267d0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
267e0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
267f0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
26800 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
26810 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
26820 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
26830 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
26840 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
26850 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
26860 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
26870 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
26880 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
26890 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
268a0 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
268b0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
268c0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
268d0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
268e0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
268f0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
26900 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
26910 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
26920 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
26930 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
26940 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
26950 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
26960 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
26970 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
26980 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
26990 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
269a0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
269b0 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
269c0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
269d0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
269e0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
269f0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
26a00 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
26a10 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
26a20 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
26a30 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
26a40 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
26a50 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
26a60 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
26a70 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
26a80 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
26a90 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
26aa0 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
26ab0 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
26ac0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
26ad0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
26ae0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
26af0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
26b00 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
26b10 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
26b20 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
26b30 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
26b40 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
26b50 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
26b60 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
26b70 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
26b80 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
26b90 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
26ba0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
26bb0 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
26bc0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
26bd0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
26be0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
26bf0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
26c00 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
26c10 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
26c20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
26c30 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
26c40 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
26c50 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26c60 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69  b?vfs=unix-dotfi
26c70 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  le <td>.**      
26c80 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
26c90 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26ca0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
26cb0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f  ial VFS "unix-do
26cc0 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20  tfile".**       
26cd0 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74     that uses dot
26ce0 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20  -files in place 
26cf0 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72  of posix advisor
26d00 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74  y locking..** <t
26d10 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
26d20 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
26d30 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
26d40 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
26d50 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
26d60 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
26d70 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
26d80 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
26d90 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
26da0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
26db0 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
26dc0 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
26dd0 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
26de0 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
26df0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
26e00 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
26e10 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
26e20 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
26e30 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
26e40 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
26e50 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
26e60 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
26e70 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
26e80 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
26e90 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
26ea0 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
26eb0 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
26ec0 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
26ed0 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
26ee0 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
26ef0 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
26f00 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
26f10 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
26f20 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
26f30 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
26f40 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
26f50 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
26f60 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
26f70 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
26f80 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
26f90 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
26fa0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
26fb0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
26fc0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
26fd0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
26fe0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
26ff0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
27000 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
27010 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
27020 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27030 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
27040 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
27050 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
27060 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
27070 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
27080 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
27090 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
270a0 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
270b0 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
270c0 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
270d0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
270e0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
270f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
27100 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
27110 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
27120 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
27130 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
27140 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
27150 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
27160 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
27170 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
27180 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
27190 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
271a0 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
271b0 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
271c0 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
271d0 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
271e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
271f0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
27200 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ory].*/.int sqli
27210 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
27220 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
27230 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
27240 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
27250 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
27260 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
27270 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
27280 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
27290 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
272a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
272b0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
272c0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
272d0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
272e0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
272f0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
27300 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
27310 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
27320 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
27330 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
27340 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
27350 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
27360 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
27370 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
27380 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
27390 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
273a0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
273b0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
273c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
273d0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
273e0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
273f0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
27400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
27410 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
27420 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
27430 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
27440 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
27450 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
27460 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
27470 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
27480 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
27490 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
274a0 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
274b0 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
274c0 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
274d0 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
274e0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
274f0 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
27500 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
27510 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
27520 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
27530 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
27540 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
27550 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
27560 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
27570 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
27580 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
27590 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
275a0 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
275b0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
275c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
275d0 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
275e0 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
275f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
27600 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
27610 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
27620 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
27630 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
27640 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
27650 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
27660 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
27670 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
27680 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
27690 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
276a0 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
276b0 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
276c0 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
276d0 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
276e0 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
276f0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27700 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
27710 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
27720 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
27730 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27740 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
27750 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
27760 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
27770 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
27780 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
27790 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
277a0 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
277b0 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
277c0 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
277d0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
277e0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
277f0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
27800 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
27810 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
27820 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
27830 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
27840 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
27850 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
27860 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
27870 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
27880 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
27890 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
278a0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
278b0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
278c0 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
278d0 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
278e0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
278f0 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
27900 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
27910 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
27920 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
27930 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
27940 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
27950 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
27960 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
27970 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
27980 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
27990 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
279a0 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
279b0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
279c0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
279d0 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
279e0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
279f0 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
27a00 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
27a10 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
27a20 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
27a30 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
27a40 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
27a50 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
27a60 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
27a70 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
27a80 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
27a90 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
27aa0 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
27ab0 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
27ac0 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
27ad0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
27ae0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
27af0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
27b00 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
27b10 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
27b20 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27b30 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
27b40 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
27b50 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
27b60 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
27b70 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
27b80 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
27b90 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
27ba0 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
27bb0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
27bc0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
27bd0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
27be0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
27bf0 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
27c00 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
27c10 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
27c20 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
27c30 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
27c40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
27c50 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  m);.int sqlite3_
27c60 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
27c70 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
27c80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
27c90 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
27ca0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
27cb0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
27cc0 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
27cd0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
27ce0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
27cf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
27d00 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
27d10 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ssages.** METHOD
27d20 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
27d30 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
27d40 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ent sqlite3_* AP
27d50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
27d60 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61  d with .** [data
27d70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
27d80 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20   D failed, then 
27d90 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  the sqlite3_errc
27da0 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65  ode(D) interface
27db0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
27dc0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
27dd0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
27de0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
27df0 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20  for that.** API 
27e00 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20  call..** If the 
27e10 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
27e20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73  call was success
27e30 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ful,.** then the
27e40 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
27e50 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
27e60 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
27e70 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
27e80 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
27e90 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
27ea0 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
27eb0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
27ec0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
27ed0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
27ee0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
27ef0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
27f00 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
27f10 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
27f20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27f30 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
27f40 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
27f50 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
27f60 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
27f70 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
27f80 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
27f90 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
27fa0 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
27fb0 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
27fc0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
27fd0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
27fe0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
27ff0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
28000 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
28010 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
28020 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
28030 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
28040 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
28050 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
28060 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
28070 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
28080 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
28090 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
280a0 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
280b0 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  tions.)^.**.** ^
280c0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73  The sqlite3_errs
280d0 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  tr() interface r
280e0 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69  eturns the Engli
280f0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
28100 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62  .** that describ
28110 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63  es the [result c
28120 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a  ode], as UTF-8..
28130 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
28140 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
28150 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
28160 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
28170 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e  ly.** and must n
28180 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74  ot be freed by t
28190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e  he application)^
281a0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
281b0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
281c0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
281d0 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
281e0 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
281f0 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
28200 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
28210 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
28220 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
28230 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
28240 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
28250 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
28260 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
28270 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
28280 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
28290 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
282a0 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
282b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
282c0 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
282d0 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
282e0 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
282f0 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
28300 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
28310 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
28320 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
28330 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
28340 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
28350 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
28360 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
28370 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
28380 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
28390 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
283a0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
283b0 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
283c0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
283d0 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
283e0 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
283f0 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
28400 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
28410 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
28420 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
28430 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
28440 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
28450 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
28460 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
28470 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
28480 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
28490 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
284a0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
284b0 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
284c0 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  t be set..*/.int
284d0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
284e0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
284f0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
28500 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
28510 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
28520 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
28530 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
28540 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28550 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
28560 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68  ite3*);.const ch
28570 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
28580 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
28590 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72  CAPI3REF: Prepar
285a0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
285b0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
285c0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
285d0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
285e0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
285f0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
28600 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
28610 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
28620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
28630 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  hat.** has been 
28640 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69  compiled into bi
28650 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73  nary form and is
28660 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61   ready to be eva
28670 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  luated..**.** Th
28680 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20  ink of each SQL 
28690 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73  statement as a s
286a0 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72  eparate computer
286b0 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a   program.  The.*
286c0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
286d0 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f  ext is source co
286e0 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20  de.  A prepared 
286f0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
28700 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70   .** is the comp
28710 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65  iled object code
28720 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20  .  All SQL must 
28730 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  be converted int
28740 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  o a.** prepared 
28750 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65  statement before
28760 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a   it can be run..
28770 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63  **.** The life-c
28780 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72  ycle of a prepar
28790 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
287a0 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73  ect usually goes
287b0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
287c0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
287d0 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72  reate the prepar
287e0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
287f0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
28800 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28810 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
28820 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65  alues to [parame
28830 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
28840 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
28850 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
28860 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
28870 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
28880 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
28890 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
288a0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
288b0 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  Reset the prepar
288c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
288d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
288e0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
288f0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
28900 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
28910 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
28920 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
28930 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
28940 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
28950 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
28960 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  >.*/.typedef str
28970 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
28980 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
28990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
289a0 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
289b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
289c0 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e3.**.** ^(This 
289d0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
289e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
289f0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
28a00 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
28a10 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
28a20 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
28a30 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
28a40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
28a50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
28a60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
28a70 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
28a80 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
28a90 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
28aa0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
28ab0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
28ac0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
28ad0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
28ae0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
28af0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
28b00 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
28b10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
28b20 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
28b30 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
28b40 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
28b50 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
28b60 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
28b70 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
28b80 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
28b90 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
28ba0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
28bb0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
28bc0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
28bd0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
28be0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
28bf0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
28c00 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
28c10 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
28c20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
28c30 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
28c40 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
28c50 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
28c60 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
28c70 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
28c80 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
28c90 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
28ca0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
28cb0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
28cc0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
28cd0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
28ce0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
28cf0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
28d00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
28d10 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
28d20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
28d30 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
28d40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
28d50 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
28d60 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
28d70 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
28d80 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
28d90 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
28da0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
28db0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
28dc0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
28dd0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
28de0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
28df0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
28e00 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
28e10 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
28e20 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
28e30 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
28e40 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
28e50 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
28e60 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
28e70 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
28e80 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
28e90 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
28ea0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
28eb0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
28ec0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
28ed0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
28ee0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
28ef0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
28f00 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
28f10 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
28f20 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
28f30 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
28f40 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
28f50 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
28f60 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
28f70 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
28f80 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
28f90 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
28fa0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
28fb0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
28fc0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
28fd0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
28fe0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
28ff0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
29000 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
29010 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
29020 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
29030 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
29040 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
29050 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
29060 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
29070 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
29080 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
29090 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
290a0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
290b0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
290c0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
290d0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
290e0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
290f0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
29100 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
29110 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
29120 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
29130 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
29140 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
29150 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
29160 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
29170 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
29180 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
29190 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
291a0 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
291b0 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
291c0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
291d0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
291e0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
291f0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
29200 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
29210 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
29220 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
29230 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
29240 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
29250 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
29260 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
29270 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
29280 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
29290 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
292a0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
292b0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
292c0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
292d0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
292e0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
292f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
29300 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
29310 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
29320 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
29330 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29340 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
29350 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
29360 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
29370 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
29380 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29390 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
293a0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
293b0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
293c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
293d0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
293e0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
293f0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
29400 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29410 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
29420 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29430 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
29440 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29450 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
29460 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
29470 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
29480 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
29490 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
294a0 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
294b0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
294c0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
294d0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
294e0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
294f0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
29500 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29510 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
29520 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29530 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
29540 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29550 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
29560 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
29570 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
29580 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
29590 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
295a0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
295b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
295c0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
295d0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
295e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
295f0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
29600 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
29610 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
29620 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29630 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
29640 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29650 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
29660 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29670 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
29680 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
29690 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
296a0 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
296b0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
296c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
296d0 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e   This limit is n
296e0 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ot currently.** 
296f0 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68  enforced, though
29700 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61   that might be a
29710 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74  dded in some fut
29720 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
29730 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e  * SQLite.</dd>)^
29740 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29750 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
29760 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
29770 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
29780 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
29790 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
297a0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
297b0 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
297c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
297d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
297e0 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
297f0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
29800 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
29810 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29820 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
29830 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
29840 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
29850 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29860 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
29870 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
29880 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
29890 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
298a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
298b0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
298c0 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
298d0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
298e0 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
298f0 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
29900 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29910 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
29920 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
29930 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29940 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
29950 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29960 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e   maximum index n
29970 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
29980 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
29990 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
299a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
299b0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
299c0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
299d0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
299e0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
299f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
29a00 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
29a10 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
29a20 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29a30 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
29a40 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64  R_THREADS]] ^(<d
29a50 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  t>SQLITE_LIMIT_W
29a60 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64  ORKER_THREADS</d
29a70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29a80 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
29a90 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72  auxiliary worker
29aa0 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20   threads that a 
29ab0 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61  single.** [prepa
29ac0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d  red statement] m
29ad0 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e  ay start.</dd>)^
29ae0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
29af0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29b00 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
29b10 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
29b20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29b30 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
29b40 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
29b50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29b60 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
29b70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
29b80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29b90 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
29ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
29bb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29bc0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
29bd0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
29be0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
29bf0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
29c00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29c10 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
29c20 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
29c30 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
29c40 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
29c50 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
29c60 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
29c70 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
29c80 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
29c90 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
29ca0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
29cb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
29cc0 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
29cd0 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
29ce0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
29cf0 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
29d00 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
29d10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
29d20 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20  KER_THREADS     
29d30 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20        11../*.** 
29d40 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
29d50 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
29d60 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
29d70 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
29d80 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45   compiler}.** ME
29d90 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
29da0 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
29db0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
29dc0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
29dd0 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
29de0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
29df0 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
29e00 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
29e10 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
29e20 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
29e30 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
29e40 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
29e50 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
29e60 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
29e70 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
29e80 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
29e90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
29ea0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
29eb0 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
29ec0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
29ed0 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
29ee0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
29ef0 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
29f00 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
29f10 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
29f20 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
29f30 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
29f40 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
29f50 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
29f60 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
29f70 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
29f80 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
29f90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
29fa0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
29fb0 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
29fc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29fd0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
29fe0 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
29ff0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
2a000 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
2a010 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67   argument is neg
2a020 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c  ative, then zSql
2a030 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
2a040 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
2a050 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
2a060 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69   nByte is positi
2a070 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
2a080 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2a090 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
2a0a0 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65  zSql.  ^If nByte
2a0b0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e   is zero, then n
2a0c0 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  o prepared.** st
2a0d0 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72  atement is gener
2a0e0 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ated..** If the 
2a0f0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61  caller knows tha
2a100 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
2a110 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
2a120 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a  minated, then.**
2a130 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
2a140 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  l performance ad
2a150 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69  vantage to passi
2a160 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
2a170 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
2a180 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2a190 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
2a1a0 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
2a1b0 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
2a1c0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e   nul-terminator.
2a1d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
2a1e0 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
2a1f0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
2a200 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
2a210 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
2a220 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
2a230 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
2a240 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2a250 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2a260 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
2a270 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
2a280 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
2a290 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
2a2a0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
2a2b0 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
2a2c0 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
2a2d0 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
2a2e0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
2a2f0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
2a300 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2a310 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
2a320 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
2a330 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
2a340 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
2a350 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
2a360 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
2a370 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
2a380 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
2a390 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
2a3a0 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
2a3b0 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
2a3c0 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
2a3d0 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
2a3e0 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
2a3f0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
2a400 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
2a410 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
2a420 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
2a430 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
2a440 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2a450 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
2a460 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
2a470 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
2a480 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
2a490 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
2a4a0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2a4b0 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
2a4c0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2a4d0 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
2a4e0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
2a4f0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2a500 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
2a510 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a520 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
2a530 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
2a540 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
2a550 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
2a560 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
2a570 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
2a580 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2a590 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
2a5a0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2a5b0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
2a5c0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
2a5d0 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
2a5e0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2a5f0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
2a600 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
2a610 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
2a620 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2a630 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
2a640 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2a650 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2a660 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
2a670 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
2a680 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
2a690 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
2a6a0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
2a6b0 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
2a6c0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
2a6d0 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
2a6e0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
2a6f0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
2a700 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
2a710 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
2a720 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
2a730 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2a740 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
2a750 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
2a760 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
2a770 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
2a780 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73  run it again. As
2a790 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45   many as [SQLITE
2a7a0 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52  _MAX_SCHEMA_RETR
2a7b0 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69  Y].** retries wi
2a7c0 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20  ll occur before 
2a7d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67  sqlite3_step() g
2a7e0 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75  ives up and retu
2a7f0 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  rns an error..**
2a800 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2a810 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
2a820 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
2a830 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2a840 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
2a850 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
2a860 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
2a870 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2a880 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
2a890 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
2a8a0 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
2a8b0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
2a8c0 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
2a8d0 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
2a8e0 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
2a8f0 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
2a900 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
2a910 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
2a920 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
2a930 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
2a940 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
2a950 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
2a960 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
2a970 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
2a980 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
2a990 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
2a9a0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
2a9b0 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
2a9c0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
2a9d0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
2a9e0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2a9f0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2aa00 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
2aa10 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
2aa20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
2aa30 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
2aa40 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
2aa50 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
2aa60 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2aa70 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
2aa80 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
2aa90 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
2aaa0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2aab0 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
2aac0 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
2aad0 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
2aae0 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
2aaf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ab00 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
2ab10 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
2ab20 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
2ab30 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
2ab40 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
2ab50 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
2ab60 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2ab70 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
2ab80 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
2ab90 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2aba0 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
2abb0 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
2abc0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
2abd0 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
2abe0 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
2abf0 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
2ac00 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
2ac10 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
2ac20 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
2ac30 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
2ac40 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
2ac50 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
2ac60 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
2ac70 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c   enabled..** </l
2ac80 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
2ac90 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2aca0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
2acb0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2acc0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2acd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2ace0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2acf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2ad00 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2ad10 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2ad20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2ad30 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2ad40 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2ad50 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2ad60 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2ad70 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2ad80 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2ad90 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2ada0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2adb0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2adc0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2add0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2ade0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
2adf0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2ae00 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2ae10 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2ae20 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2ae30 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2ae40 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2ae50 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2ae60 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2ae70 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2ae80 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2ae90 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2aea0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2aeb0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2aec0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2aed0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2aee0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2aef0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2af00 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2af10 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2af20 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
2af30 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2af40 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2af50 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2af60 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2af70 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2af80 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2af90 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2afa0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2afb0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2afc0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2afd0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2afe0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2aff0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2b000 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2b010 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2b020 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2b030 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2b040 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2b050 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2b060 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2b070 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
2b080 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2b090 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2b0a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2b0b0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2b0c0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2b0d0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2b0e0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2b0f0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2b100 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2b110 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2b120 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2b130 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2b140 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2b150 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2b160 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2b170 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2b180 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2b190 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2b1a0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2b1b0 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2b1c0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2b1d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2b1e0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2b1f0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  The sqlite3_sql(
2b200 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2b210 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2b220 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  o a copy of the 
2b230 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78  UTF-8.** SQL tex
2b240 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2b250 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b260 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73  ment] P if P was
2b270 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 65  .** created by e
2b280 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2b290 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2b2a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b2b0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  16_v2()]..** ^Th
2b2c0 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2b2d0 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  ed_sql(P) interf
2b2e0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2b2f0 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38  inter to a UTF-8
2b300 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
2b310 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65  ining the SQL te
2b320 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73  xt of prepared s
2b330 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a  tatement P with.
2b340 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  ** [bound parame
2b350 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a  ters] expanded..
2b360 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2b370 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72  ple, if a prepar
2b380 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2b390 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
2b3a0 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53  e SQL.** text "S
2b3b0 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2b3c0 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65   and if paramete
2b3d0 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20  r $abc is bound 
2b3e0 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a  to integer 2345.
2b3f0 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72  ** and parameter
2b400 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64   :xyz is unbound
2b410 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  , then sqlite3_s
2b420 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ql() will return
2b430 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
2b440 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54   string, "SELECT
2b450 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20   $abc,:xyz" but 
2b460 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2b470 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72  _sql().** will r
2b480 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33  eturn "SELECT 23
2b490 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a  45,NULL".)^.**.*
2b4a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2b4b0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e  xpanded_sql() in
2b4c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b4d0 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
2b4e0 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  ient memory.** i
2b4f0 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68  s available to h
2b500 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20  old the result, 
2b510 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74  or if the result
2b520 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2b530 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d  e.** the maximum
2b540 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64   string length d
2b550 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
2b560 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c   [SQLITE_LIMIT_L
2b570 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ENGTH]..**.** ^T
2b580 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
2b590 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
2b5a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2b5b0 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65   limits the size
2b5c0 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72   of.** bound par
2b5d0 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e  ameter expansion
2b5e0 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  s.  ^The [SQLITE
2b5f0 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d  _OMIT_TRACE] com
2b600 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
2b610 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74  ion causes sqlit
2b620 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2b630 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75  ) to always retu
2b640 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  rn NULL..**.** ^
2b650 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2b660 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  ned by sqlite3_s
2b670 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64  ql(P) is managed
2b680 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69   by SQLite and i
2b690 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2b6a0 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68  ly freed when th
2b6b0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2b6c0 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2b6d0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2b6e0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2b6f0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2b700 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2b710 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2b720 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2b730 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2b740 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2b750 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2b760 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2b770 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2b780 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f  3_free()]..*/.co
2b790 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2b7a0 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
2b7b0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72  mt *pStmt);.char
2b7c0 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   *sqlite3_expand
2b7d0 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2b7e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2b7f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2b800 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
2b810 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
2b820 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
2b830 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2b840 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2b850 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2b860 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
2b870 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2b880 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2b890 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
2b8a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2b8b0 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
2b8c0 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
2b8d0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
2b8e0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2b8f0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
2b900 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
2b910 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b920 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
2b930 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
2b940 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
2b950 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2b960 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
2b970 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
2b980 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2b990 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
2b9a0 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
2b9b0 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
2b9c0 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
2b9d0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
2b9e0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
2b9f0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
2ba00 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
2ba10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2ba20 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
2ba30 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
2ba40 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
2ba50 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
2ba60 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
2ba70 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
2ba80 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
2ba90 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
2baa0 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
2bab0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
2bac0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2bad0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
2bae0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
2baf0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2bb00 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
2bb10 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
2bb20 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
2bb30 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
2bb40 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
2bb50 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
2bb60 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
2bb70 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
2bb80 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
2bb90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2bba0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2bbb0 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
2bbc0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
2bbd0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
2bbe0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
2bbf0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2bc00 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
2bc10 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
2bc20 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
2bc30 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
2bc40 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
2bc50 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
2bc60 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
2bc70 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
2bc80 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
2bc90 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2bca0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2bcb0 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
2bcc0 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
2bcd0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
2bce0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
2bcf0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
2bd00 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
2bd10 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
2bd20 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
2bd30 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2bd40 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
2bd50 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  k..** ^The sqlit
2bd60 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2bd70 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2bd80 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42  urns true for [B
2bd90 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b  EGIN] since.** [
2bda0 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65  BEGIN] merely se
2bdb0 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67  ts internal flag
2bdc0 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49  s, but the [BEGI
2bdd0 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54  N|BEGIN IMMEDIAT
2bde0 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e  E] and.** [BEGIN
2bdf0 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45  |BEGIN EXCLUSIVE
2be00 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f  ] commands do to
2be10 75 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  uch the database
2be20 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74   and so.** sqlit
2be30 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2be40 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  () returns false
2be50 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61   for those comma
2be60 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
2be70 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2be80 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
2be90 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2bea0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2beb0 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
2bec0 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
2bed0 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54  een Reset.** MET
2bee0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2bef0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2bf00 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2bf10 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2bf20 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2bf30 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
2bf40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bf50 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
2bf60 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
2bf70 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
2bf80 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2bf90 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20  but has neither 
2bfa0 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
2bfb0 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  n (returned.** [
2bfc0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f  SQLITE_DONE] fro
2bfd0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  m [sqlite3_step(
2bfe0 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e  S)]) nor.** been
2bff0 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
2c000 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
2c010 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
2c020 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
2c030 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2c040 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
2c050 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
2c060 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
2c070 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
2c080 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
2c090 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
2c0a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c0b0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
2c0c0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2c0d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2c0e0 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
2c0f0 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
2c100 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
2c110 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
2c120 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
2c130 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
2c140 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
2c150 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c160 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
2c170 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
2c180 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
2c190 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
2c1a0 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
2c1b0 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
2c1c0 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
2c1d0 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
2c1e0 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
2c1f0 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
2c200 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
2c210 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
2c220 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
2c230 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
2c240 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
2c250 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2c260 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
2c270 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
2c280 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
2c290 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
2c2a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c2b0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
2c2c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
2c2d0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
2c2e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
2c2f0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
2c300 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
2c310 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
2c320 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
2c330 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
2c340 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2c350 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
2c360 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
2c370 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
2c380 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
2c390 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
2c3a0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
2c3b0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
2c3c0 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
2c3d0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
2c3e0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
2c3f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2c400 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
2c410 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
2c420 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
2c430 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
2c440 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
2c450 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c460 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
2c470 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
2c480 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
2c490 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
2c4a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c4b0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
2c4c0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
2c4d0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
2c4e0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
2c4f0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
2c500 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
2c510 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
2c520 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c530 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
2c540 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20  e3_value_dup()] 
2c550 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2c560 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75   used to constru
2c570 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f  ct a new .** pro
2c580 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c590 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70  alue from an unp
2c5a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c5b0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
2c5c0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
2c5d0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
2c5e0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
2c5f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
2c600 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
2c610 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
2c620 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2c630 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
2c640 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c650 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
2c660 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
2c670 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2c680 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c690 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
2c6a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
2c6b0 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
2c6c0 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
2c6d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
2c6e0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
2c6f0 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2c700 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
2c710 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
2c720 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
2c730 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
2c740 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
2c750 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
2c760 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
2c770 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2c780 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
2c790 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
2c7a0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2c7b0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2c7c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2c7d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
2c7e0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
2c7f0 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
2c800 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
2c810 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
2c820 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
2c830 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
2c840 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
2c850 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
2c860 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
2c870 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2c880 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2c890 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2c8a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
2c8b0 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
2c8c0 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
2c8d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c8e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
2c8f0 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
2c900 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
2c910 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
2c920 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
2c930 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2c940 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
2c950 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
2c960 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2c970 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
2c980 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2c990 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2c9a0 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
2c9b0 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
2c9c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2c9d0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
2c9e0 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
2c9f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2ca00 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2ca10 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2ca20 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
2ca30 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
2ca40 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
2ca50 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
2ca60 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
2ca70 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
2ca80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2ca90 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
2caa0 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
2cab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
2cac0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2cad0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
2cae0 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
2caf0 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
2cb00 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
2cb10 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
2cb20 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
2cb30 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
2cb40 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
2cb50 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
2cb60 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2cb70 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
2cb80 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2cb90 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
2cba0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2cbb0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
2cbc0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2cbd0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2cbe0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2cbf0 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
2cc00 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
2cc10 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
2cc20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2cc30 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
2cc40 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
2cc50 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2cc60 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
2cc70 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
2cc80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
2cc90 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
2cca0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
2ccb0 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
2ccc0 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
2ccd0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
2cce0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2ccf0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2cd00 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2cd10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cd20 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
2cd30 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
2cd40 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
2cd50 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
2cd60 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
2cd70 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
2cd80 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
2cd90 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
2cda0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
2cdb0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
2cdc0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
2cdd0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2cde0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2cdf0 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
2ce00 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
2ce10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
2ce20 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
2ce30 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
2ce40 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
2ce50 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
2ce60 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
2ce70 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
2ce80 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
2ce90 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
2cea0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
2ceb0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
2cec0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
2ced0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
2cee0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
2cef0 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
2cf00 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
2cf10 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
2cf20 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
2cf30 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
2cf40 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
2cf50 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
2cf60 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
2cf70 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
2cf80 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
2cf90 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
2cfa0 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
2cfb0 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
2cfc0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
2cfd0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
2cfe0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2cff0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
2d000 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2d010 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2d020 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2d030 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
2d040 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
2d050 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2d060 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
2d070 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
2d080 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d090 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
2d0a0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
2d0b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2d0c0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2d0d0 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
2d0e0 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
2d0f0 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
2d100 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
2d110 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
2d120 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
2d130 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
2d140 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
2d150 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
2d160 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2d170 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
2d180 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
2d190 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
2d1a0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
2d1b0 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
2d1c0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
2d1d0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
2d1e0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
2d1f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2d200 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2d210 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
2d220 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
2d230 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
2d240 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
2d250 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
2d260 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
2d270 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
2d280 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
2d290 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
2d2a0 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
2d2b0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2d2c0 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
2d2d0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
2d2e0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2d2f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
2d300 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
2d310 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
2d320 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
2d330 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2d340 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2d350 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2d360 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20  _text16().** or 
2d370 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2d380 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  b() is a NULL po
2d390 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66  inter then the f
2d3a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a  ourth parameter.
2d3b0 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e  ** is ignored an
2d3c0 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74  d the end result
2d3d0 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
2d3e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2d3f0 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  l()..**.** ^(In 
2d400 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
2d410 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
2d420 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
2d430 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2d440 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2d450 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2d460 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
2d470 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
2d480 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
2d490 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
2d4a0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
2d4b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2d4c0 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
2d4d0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2d4e0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2d4f0 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2d500 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d510 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74  16().** is negat
2d520 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65  ive, then the le
2d530 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
2d540 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
2d550 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
2d560 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2d570 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2d580 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
2d590 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2d5a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
2d5b0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2d5c0 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f  n.** the behavio
2d5d0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2d5e0 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61  ** If a non-nega
2d5f0 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61  tive fourth para
2d600 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65  meter is provide
2d610 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  d to sqlite3_bin
2d620 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73  d_text().** or s
2d630 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d640 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  16() or sqlite3_
2d650 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68  bind_text64() th
2d660 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d  en.** that param
2d670 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
2d680 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
2d690 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
2d6a0 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
2d6b0 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
2d6c0 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
2d6d0 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
2d6e0 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
2d6f0 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
2d700 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
2d710 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
2d720 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
2d730 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
2d740 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
2d750 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
2d760 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
2d770 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
2d780 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
2d790 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
2d7a0 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
2d7b0 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
2d7c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2d7d0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
2d7e0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42  rgument to the B
2d7f0 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62  LOB and string b
2d800 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65  inding interface
2d810 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75  s.** is a destru
2d820 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
2d830 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2d840 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
2d850 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
2d860 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
2d870 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
2d880 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
2d890 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2d8a0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2d8b0 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
2d8c0 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69   to bind API fai
2d8d0 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ls..** ^If the f
2d8e0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
2d8f0 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
2d900 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
2d910 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
2d920 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
2d930 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
2d940 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
2d950 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
2d960 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
2d970 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
2d980 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
2d990 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
2d9a0 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
2d9b0 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
2d9c0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
2d9d0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2d9e0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
2d9f0 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
2da00 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
2da10 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2da20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
2da30 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20  *.** ^The sixth 
2da40 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2da50 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2da60 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
2da70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2da80 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2da90 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2daa0 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
2dab0 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73  UTF16LE].** to s
2dac0 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64  pecify the encod
2dad0 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20  ing of the text 
2dae0 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
2daf0 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74  ameter.  If.** t
2db00 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2db10 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2db20 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f  d_text64() is no
2db30 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
2db40 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73  allowed values s
2db50 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69  hown above, or i
2db60 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  f the text encod
2db70 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
2db80 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63  .** from the enc
2db90 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20  oding specified 
2dba0 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72  by the sixth par
2dbb0 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
2dbc0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
2dbd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2dbe0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2dbf0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
2dc00 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
2dc10 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
2dc20 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
2dc30 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
2dc40 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
2dc50 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
2dc60 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
2dc70 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
2dc80 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
2dc90 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
2dca0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
2dcb0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
2dcc0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
2dcd0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
2dce0 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
2dcf0 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
2dd00 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
2dd10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2dd20 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
2dd30 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
2dd40 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
2dd50 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
2dd60 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
2dd70 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
2dd80 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
2dd90 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
2dda0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2ddb0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
2ddc0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
2ddd0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
2dde0 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2ddf0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
2de00 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
2de10 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
2de20 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
2de30 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
2de40 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
2de50 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
2de60 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
2de70 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
2de80 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
2de90 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
2dea0 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
2deb0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
2dec0 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
2ded0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2dee0 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
2def0 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
2df00 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2df10 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2df20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
2df30 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
2df40 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
2df50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2df60 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
2df70 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
2df80 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
2df90 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
2dfa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2dfb0 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
2dfc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2dfd0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
2dfe0 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
2dff0 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
2e000 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
2e010 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69  QLITE_TOOBIG] mi
2e020 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2e030 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  if the size of a
2e040 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a   string or BLOB.
2e050 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74  ** exceeds limit
2e060 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71  s imposed by [sq
2e070 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2e080 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2e090 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  H]) or.** [SQLIT
2e0a0 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  E_MAX_LENGTH]..*
2e0b0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
2e0c0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2e0d0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
2e0e0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
2e0f0 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
2e100 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
2e110 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
2e120 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
2e130 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2e140 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e150 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
2e160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e170 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2e180 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2e190 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2e1a0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2e1b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
2e1c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e1d0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2e1e0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
2e1f0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2e200 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73  e3_bind_blob64(s
2e210 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e220 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2e230 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
2e240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e250 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2e260 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2e270 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
2e280 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e290 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
2e2a0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2e2b0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2e2c0 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
2e2d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2e2e0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2e2f0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
2e300 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
2e310 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
2e320 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e330 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2e340 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
2e350 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74  _stmt*,int,const
2e360 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28   char*,int,void(
2e370 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2e380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2e390 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2e3a0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2e3b0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2e3c0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2e3d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2e3e0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2e3f0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
2e400 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
2e410 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2e420 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2e430 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
2e440 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
2e450 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ing);.int sqlite
2e460 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
2e470 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2e480 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
2e490 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2e4a0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2e4b0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2e4c0 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e   int, int n);.in
2e4d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2e4e0 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  eroblob64(sqlite
2e4f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2e500 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a  lite3_uint64);..
2e510 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e520 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
2e530 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48  rameters.** METH
2e540 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e550 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2e560 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
2e570 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
2e580 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
2e590 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
2e5a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e5b0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
2e5c0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
2e5d0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
2e5e0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
2e5f0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
2e600 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
2e610 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
2e620 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
2e630 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
2e640 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
2e650 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
2e660 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
2e670 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
2e680 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2e690 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
2e6a0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2e6b0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
2e6c0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
2e6d0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
2e6e0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
2e6f0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
2e700 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
2e710 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
2e720 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
2e730 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2e740 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
2e750 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
2e760 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
2e770 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
2e780 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2e790 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2e7a0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2e7b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e7c0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2e7d0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2e7e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e7f0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
2e800 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2e810 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
2e820 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2e830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2e840 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
2e850 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f  rameter.** METHO
2e860 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2e870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e880 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e890 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
2e8a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
2e8b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2e8c0 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
2e8d0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
2e8e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e8f0 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
2e900 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2e910 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
2e920 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2e930 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
2e940 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
2e950 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
2e960 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2e970 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2e980 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
2e990 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
2e9a0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
2e9b0 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
2e9c0 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
2e9d0 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
2e9e0 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
2e9f0 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
2ea00 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
2ea10 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
2ea20 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
2ea30 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
2ea40 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
2ea50 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
2ea60 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
2ea70 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
2ea80 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
2ea90 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
2eaa0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
2eab0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
2eac0 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
2ead0 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
2eae0 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
2eaf0 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
2eb00 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
2eb10 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
2eb20 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2eb30 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
2eb40 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
2eb50 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
2eb60 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
2eb70 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
2eb80 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
2eb90 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
2eba0 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
2ebb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ebc0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2ebd0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2ebe0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2ebf0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2ec00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ec10 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2ec20 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2ec30 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ec40 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
2ec50 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2ec60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ec70 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2ec80 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
2ec90 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
2eca0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
2ecb0 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
2ecc0 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  me.** METHOD: sq
2ecd0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2ece0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
2ecf0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
2ed00 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
2ed10 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
2ed20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
2ed30 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
2ed40 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
2ed50 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
2ed60 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2ed70 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2ed80 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
2ed90 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
2eda0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
2edb0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
2edc0 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
2edd0 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
2ede0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
2edf0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
2ee00 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
2ee10 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
2ee20 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
2ee30 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
2ee40 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2ee50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2ee60 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2ee70 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2ee80 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2ee90 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2eea0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2eeb0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2eec0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2eed0 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  e()]..*/.int sql
2eee0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2eef0 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
2ef00 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
2ef10 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
2ef20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2ef30 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
2ef40 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
2ef50 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48  tatement.** METH
2ef60 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ef70 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
2ef80 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
2ef90 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
2efa0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
2efb0 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
2efc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2efd0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
2efe0 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
2eff0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2f000 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
2f010 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
2f020 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
2f030 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
2f040 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2f050 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2f060 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2f070 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2f080 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
2f090 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2f0a0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2f0b0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2f0c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2f0d0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2f0e0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
2f0f0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
2f100 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2f110 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
2f120 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74   returns 0, that
2f130 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b   means the .** [
2f140 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f150 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64  nt] returns no d
2f160 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
2f170 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
2f180 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74  * ^However, just
2f190 20 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f   because this ro
2f1a0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
2f1b0 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20  positive number 
2f1c0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e  does not.** mean
2f1d0 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72   that one or mor
2f1e0 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77  e rows of data w
2f1f0 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
2f200 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74    ^A SELECT stat
2f210 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ement.** will al
2f220 77 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69  ways have a posi
2f230 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  tive sqlite3_col
2f240 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20  umn_count() but 
2f250 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2f260 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2f270 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
2f280 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65   the table conte
2f290 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74  nt, it might ret
2f2a0 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a  urn no rows..**.
2f2b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2f2c0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2f2d0 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
2f2e0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2f2f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2f300 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2f310 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
2f320 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
2f330 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
2f340 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2f350 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2f360 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
2f370 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
2f380 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
2f390 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
2f3a0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2f3b0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2f3c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2f3d0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
2f3e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2f3f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2f400 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2f410 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2f420 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2f430 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
2f440 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2f450 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2f460 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
2f470 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
2f480 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2f490 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f4a0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
2f4b0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
2f4c0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2f4d0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2f4e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2f4f0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
2f500 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
2f510 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
2f520 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
2f530 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
2f540 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
2f550 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
2f560 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f570 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
2f580 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2f590 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2f5a0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2f5b0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2f5c0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2f5d0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2f5e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2f5f0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2f600 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2f610 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
2f620 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
2f630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2f640 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
2f650 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2f660 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
2f670 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
2f680 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
2f690 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
2f6a0 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
2f6b0 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
2f6c0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
2f6d0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
2f6e0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
2f6f0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
2f700 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2f710 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2f720 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
2f730 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
2f740 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2f750 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
2f760 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
2f770 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
2f780 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
2f790 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
2f7a0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
2f7b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2f7c0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
2f7d0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
2f7e0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
2f7f0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2f800 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
2f810 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2f820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2f830 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f840 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
2f850 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2f860 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
2f870 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2f880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f890 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
2f8a0 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
2f8b0 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
2f8c0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f8d0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2f8e0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
2f8f0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
2f900 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
2f910 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
2f920 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
2f930 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
2f940 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
2f950 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
2f960 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2f970 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
2f980 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
2f990 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
2f9a0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
2f9b0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
2f9c0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2f9d0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
2f9e0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
2f9f0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
2fa00 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
2fa10 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
2fa20 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2fa30 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
2fa40 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
2fa50 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2fa60 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
2fa70 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2fa80 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
2fa90 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
2faa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fab0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
2fac0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2fad0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2fae0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2faf0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2fb00 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2fb10 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2fb20 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2fb30 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2fb40 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2fb50 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
2fb60 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2fb70 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
2fb80 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
2fb90 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
2fba0 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
2fbb0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
2fbc0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
2fbd0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
2fbe0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
2fbf0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
2fc00 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2fc10 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
2fc20 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
2fc30 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2fc40 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
2fc50 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2fc60 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2fc70 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
2fc80 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
2fc90 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
2fca0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
2fcb0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
2fcc0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2fcd0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
2fce0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
2fcf0 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
2fd00 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
2fd10 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2fd20 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
2fd30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2fd40 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
2fd50 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
2fd60 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
2fd70 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
2fd80 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
2fd90 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
2fda0 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
2fdb0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
2fdc0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
2fdd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2fde0 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
2fdf0 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
2fe00 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
2fe10 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
2fe20 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
2fe30 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
2fe40 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
2fe50 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
2fe60 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
2fe70 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
2fe80 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
2fe90 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
2fea0 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
2feb0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
2fec0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2fed0 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
2fee0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
2fef0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
2ff00 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
2ff10 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
2ff20 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
2ff30 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
2ff40 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
2ff50 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
2ff60 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
2ff70 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2ff80 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2ff90 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2ffa0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
2ffb0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2ffc0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
2ffd0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
2ffe0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
2fff0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
30000 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
30010 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
30020 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
30030 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
30040 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
30050 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
30060 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
30070 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
30080 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
30090 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
300a0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
300b0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
300c0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
300d0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
300e0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
300f0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
30100 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
30110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
30120 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
30130 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
30140 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
30150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
30160 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
30170 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
30180 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
30190 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
301a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
301b0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
301c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
301d0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
301e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
301f0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
30200 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30210 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
30220 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
30230 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
30240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
30250 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
30260 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
30270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
30280 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
30290 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
302a0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
302b0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
302c0 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
302d0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
302e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
302f0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
30300 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
30310 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
30320 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
30330 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
30340 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
30350 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
30360 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
30370 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
30380 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
30390 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
303a0 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
303b0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
303c0 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
303d0 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
303e0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
303f0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
30400 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
30410 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
30420 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
30430 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
30440 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
30450 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
30460 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
30470 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
30480 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
30490 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
304a0 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
304b0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
304c0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
304d0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
304e0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
304f0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
30500 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
30510 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
30520 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
30530 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
30540 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
30550 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
30560 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
30570 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
30580 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
30590 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
305a0 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
305b0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
305c0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
305d0 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
305e0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
305f0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
30600 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
30610 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
30620 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
30630 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
30640 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
30650 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
30660 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
30670 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
30680 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
30690 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
306a0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
306b0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
306c0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
306d0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
306e0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
306f0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
30700 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
30710 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
30720 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30730 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
30740 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
30750 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
30760 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
30770 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
30780 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
30790 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
307a0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
307b0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
307c0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
307d0 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
307e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
307f0 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
30800 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
30810 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
30820 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
30830 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
30840 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
30850 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
30860 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
30870 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
30880 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
30890 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
308a0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
308b0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
308c0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
308d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
308e0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
308f0 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
30900 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
30910 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
30920 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
30930 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
30940 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
30950 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
30960 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
30970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
30980 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
30990 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
309a0 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
309b0 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
309c0 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
309d0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
309e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
309f0 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
30a00 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
30a10 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
30a20 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
30a30 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
30a40 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
30a50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
30a60 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
30a70 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
30a80 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
30a90 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
30aa0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
30ab0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
30ac0 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
30ad0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
30ae0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
30af0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
30b00 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
30b10 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
30b20 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
30b30 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
30b40 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
30b50 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
30b60 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
30b70 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
30b80 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
30b90 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
30ba0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
30bb0 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
30bc0 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
30bd0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
30be0 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
30bf0 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
30c00 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
30c10 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
30c20 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
30c30 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
30c40 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
30c50 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
30c60 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
30c70 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
30c80 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
30c90 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
30ca0 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a  urs within an.**
30cb0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
30cc0 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
30cd0 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
30ce0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
30cf0 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
30d00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
30d10 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
30d20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
30d30 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
30d40 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
30d50 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
30d60 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
30d70 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
30d80 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
30d90 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
30da0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
30db0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
30dc0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
30dd0 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
30de0 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
30df0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
30e00 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
30e10 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
30e20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
30e30 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
30e40 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
30e50 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
30e60 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
30e70 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
30e80 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
30e90 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
30ea0 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
30eb0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
30ec0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
30ed0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
30ee0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
30ef0 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
30f00 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
30f10 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
30f20 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
30f30 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
30f40 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
30f50 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
30f60 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
30f70 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
30f80 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
30f90 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
30fa0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
30fb0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
30fc0 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
30fd0 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
30fe0 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
30ff0 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
31000 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
31010 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
31020 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
31030 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
31040 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
31050 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
31060 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
31070 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
31080 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
31090 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
310a0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
310b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
310c0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
310d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
310e0 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
310f0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
31100 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
31110 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
31120 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
31130 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
31140 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
31150 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
31160 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
31170 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
31180 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
31190 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
311a0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
311b0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
311c0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
311d0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
311e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
311f0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
31200 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
31210 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
31220 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
31230 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
31240 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
31250 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
31260 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
31270 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
31280 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
31290 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
312a0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
312b0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
312c0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
312d0 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
312e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
312f0 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
31300 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61  g 3.6.23.1, a ca
31310 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
31320 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72  3_reset()] was r
31330 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71  equired after sq
31340 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
31350 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a  urned anything.*
31360 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  * other than [SQ
31370 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65  LITE_ROW] before
31380 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
31390 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
313a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
313b0 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73    Failure to res
313c0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
313d0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
313e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
313f0 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75  et()] would resu
31400 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
31410 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
31420 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
31430 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
31440 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e  er [version 3.6.
31450 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33  23.1] ([dateof:3
31460 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c  .6.23.1],.** sql
31470 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
31480 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
31490 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
314a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
314b0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
314c0 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
314d0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
314e0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
314f0 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
31500 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
31510 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
31520 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
31530 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
31540 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
31550 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
31560 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
31570 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
31580 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
31590 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
315a0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
315b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
315c0 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
315d0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
315e0 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
315f0 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
31600 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
31610 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
31620 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
31630 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
31640 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
31650 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
31660 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
31670 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
31680 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
31690 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
316a0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
316b0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
316c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
316d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
316e0 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
316f0 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
31700 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
31710 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
31720 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
31730 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
31740 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
31750 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
31760 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
31770 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
31780 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
31790 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
317a0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
317b0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
317c0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
317d0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
317e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
317f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
31800 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
31810 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
31820 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
31830 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
31840 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
31850 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
31860 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
31870 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
31880 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
31890 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
318a0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
318b0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
318c0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
318d0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
318e0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
318f0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
31900 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
31910 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
31920 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
31930 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45  result set.** ME
31940 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
31950 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
31960 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
31970 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
31980 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
31990 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
319a0 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
319b0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
319c0 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
319d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
319e0 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
319f0 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
31a00 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
31a10 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
31a20 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
31a30 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
31a40 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
31a50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
31a60 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
31a70 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
31a80 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
31a90 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
31aa0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
31ab0 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
31ac0 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
31ad0 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
31ae0 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
31af0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31b00 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
31b10 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
31b20 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
31b30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
31b40 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
31b50 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
31b60 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
31b70 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
31b80 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
31b90 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
31ba0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
31bb0 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
31bc0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
31bd0 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
31be0 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
31bf0 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
31c00 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
31c10 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
31c20 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
31c30 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
31c40 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
31c50 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
31c60 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
31c70 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
31c80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
31c90 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
31ca0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
31cb0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
31cc0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
31cd0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
31ce0 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
31cf0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
31d00 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
31d10 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
31d20 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
31d30 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
31d40 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
31d50 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
31d60 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
31d70 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
31d80 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
31d90 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
31da0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
31db0 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
31dc0 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
31dd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
31de0 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
31df0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
31e00 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
31e10 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
31e20 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
31e30 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
31e40 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
31e50 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
31e60 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
31e70 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
31e80 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
31e90 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
31ea0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
31eb0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
31ec0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
31ed0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
31ee0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
31ef0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
31f00 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
31f10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31f20 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
31f30 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
31f40 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
31f50 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
31f60 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
31f70 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
31f80 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
31f90 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
31fa0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
31fb0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
31fc0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
31fd0 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
31fe0 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
31ff0 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
32000 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
32010 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
32020 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
32030 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
32040 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
32050 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
32060 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
32070 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
32080 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
32090 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
320a0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
320b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
320c0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
320d0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
320e0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
320f0 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
32100 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
32110 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
32120 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
32130 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
32140 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
32150 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
32160 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
32170 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
32180 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
32190 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
321a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
321b0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
321c0 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
321d0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
321e0 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
321f0 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
32200 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
32210 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
32220 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
32230 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
32240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
32250 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
32260 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
32270 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
32280 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
32290 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
322a0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
322b0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
322c0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
322d0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
322e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
322f0 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
32300 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
32310 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
32320 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
32330 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
32340 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
32350 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
32360 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32370 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
32380 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
32390 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
323a0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
323b0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
323c0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
323d0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
323e0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
323f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
32400 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
32410 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
32420 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
32430 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
32440 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
32450 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
32460 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
32470 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
32480 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
32490 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
324a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
324b0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
324c0 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
324d0 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
324e0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
324f0 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
32500 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
32510 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
32520 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
32540 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
32550 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
32560 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
32570 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
32580 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
32590 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
325a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
325b0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
325c0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
325d0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
325e0 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
325f0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
32600 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
32610 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
32620 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
32630 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
32640 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
32650 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
32660 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
32670 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
32680 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
32690 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
326a0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
326b0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
326c0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
326d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
326e0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
326f0 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
32700 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
32710 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
32720 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
32730 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32740 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
32750 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
32760 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
32770 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
32780 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
32790 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
327a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
327b0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
327c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
327d0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
327e0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
327f0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
32800 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
32810 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
32820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32830 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
32840 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
32850 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
32860 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
32870 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
32880 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
32890 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
328a0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
328b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
328c0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
328d0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
328e0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
328f0 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
32900 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
32910 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
32920 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
32930 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
32940 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
32950 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
32960 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
32970 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
32980 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
32990 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
329a0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
329b0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
329c0 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
329d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
329e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
329f0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
32a00 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
32a10 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32a20 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
32a30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
32a40 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
32a50 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
32a60 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
32a70 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
32a80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
32a90 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
32aa0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
32ab0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
32ac0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32ad0 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
32ae0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
32af0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
32b00 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
32b10 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
32b20 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
32b30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
32b40 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
32b50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
32b60 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
32b70 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
32b80 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
32b90 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
32ba0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
32bb0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
32bc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
32bd0 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
32be0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32bf0 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
32c00 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
32c10 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
32c20 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
32c30 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
32c40 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
32c50 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
32c60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32c70 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
32c80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32c90 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
32ca0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
32cb0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
32cc0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
32cd0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
32ce0 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
32cf0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
32d00 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
32d10 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
32d20 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
32d30 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
32d40 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
32d50 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
32d60 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
32d70 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
32d80 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
32d90 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
32da0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
32db0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c  pointer..**.** <
32dc0 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e  b>Warning:</b> ^
32dd0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
32de0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
32df0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
32e00 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
32e10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32e20 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e  lue] object.  In
32e30 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64   a multithreaded
32e40 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a   environment,.**
32e50 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
32e60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
32e70 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ject may only be
32e80 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74   used safely wit
32e90 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  h.** [sqlite3_bi
32ea0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
32eb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32ec0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
32ed0 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
32ee0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32ef0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
32f00 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
32f10 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
32f20 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
32f30 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
32f40 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
32f50 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
32f60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
32f70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
32f80 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
32f90 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
32fa0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62  _bytes()], the b
32fb0 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74  ehavior is not t
32fc0 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a  hreadsafe..**.**
32fd0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32fe0 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
32ff0 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
33000 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
33010 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
33020 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
33030 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
33040 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
33050 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
33060 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
33070 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
33080 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
33090 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
330a0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
330b0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
330c0 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
330d0 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
330e0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
330f0 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
33100 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
33110 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
33120 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
33130 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
33140 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
33150 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
33160 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
33170 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
33180 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
33190 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
331a0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
331b0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
331c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
331d0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
331e0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
331f0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
33200 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
33210 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
33220 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
33230 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
33240 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
33250 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
33260 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
33270 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
33280 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
33290 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
332a0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
332b0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
332c0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
332d0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
332e0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
332f0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
33300 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
33310 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
33320 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
33330 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
33340 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
33350 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
33360 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
33370 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
33380 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
33390 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
333a0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
333b0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
333c0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
333d0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43   BLOB    <td> [C
333e0 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20  AST] to BLOB.** 
333f0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
33400 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
33410 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
33420 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
33430 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
33440 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
33450 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
33460 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
33470 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
33480 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
33490 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
334a0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
334b0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
334c0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
334d0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
334e0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
334f0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
33500 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
33510 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
33520 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
33530 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
33540 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
33550 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
33560 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
33570 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
33580 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
33590 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
335a0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
335b0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
335c0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
335d0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
335e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
335f0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
33600 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33610 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
33620 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
33630 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
33640 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
33650 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
33660 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
33670 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
33680 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
33690 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
336a0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
336b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
336c0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
336d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
336e0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
336f0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
33700 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
33710 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
33720 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
33730 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
33740 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
33750 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
33760 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
33770 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
33780 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
33790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
337a0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
337b0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
337c0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
337d0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
337e0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
337f0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
33800 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
33810 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
33820 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
33830 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
33840 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
33850 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
33860 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
33870 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
33880 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
33890 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
338a0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
338b0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
338c0 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
338d0 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
338e0 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
338f0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
33900 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
33910 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
33920 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
33930 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
33940 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
33950 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
33960 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
33970 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
33980 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
33990 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
339a0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
339b0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
339c0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
339d0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
339e0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
339f0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
33a00 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
33a10 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
33a20 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  est policy is to
33a30 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
33a40 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
33a50 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
33a60 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
33a70 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
33a80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
33a90 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
33aa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33ab0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
33ac0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
33ad0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
33ae0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
33af0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
33b00 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
33b10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
33b20 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
33b30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
33b40 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
33b50 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
33b60 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
33b70 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
33b80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
33b90 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
33ba0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
33bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33bc0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
33bd0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
33be0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
33bf0 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
33c00 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
33c10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
33c20 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
33c30 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
33c40 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
33c50 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
33c60 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
33c70 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
33c80 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
33c90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
33ca0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
33cb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
33cc0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
33cd0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
33ce0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
33cf0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
33d00 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
33d10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33d20 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
33d30 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
33d40 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
33d50 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
33d60 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
33d70 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
33d80 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
33d90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
33da0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33db0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
33dc0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
33dd0 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
33de0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
33df0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
33e00 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
33e10 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
33e20 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f  ally.  Do <em>no
33e30 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20  t</em> pass the 
33e40 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
33e50 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
33e60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
33e70 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
33e80 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
33e90 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
33ea0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
33eb0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
33ec0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
33ed0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
33ee0 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
33ef0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
33f00 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
33f10 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
33f20 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
33f30 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
33f40 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
33f50 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
33f60 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
33f70 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
33f80 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
33f90 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
33fa0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
33fb0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
33fc0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
33fd0 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
33fe0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
33ff0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
34000 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
34010 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
34020 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
34030 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
34040 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
34050 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34060 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
34070 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
34080 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34090 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
340a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
340b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
340c0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
340d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
340e0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
340f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
34100 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
34110 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
34120 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
34130 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
34140 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
34150 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
34160 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *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 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
34190 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
341a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
341b0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
341c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
341d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
341e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
341f0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
34200 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
34210 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
34220 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
34230 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
34240 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52  ct.** DESTRUCTOR
34250 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
34260 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34270 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
34280 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
34290 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
342a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
342b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
342c0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
342d0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
342e0 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
342f0 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
34300 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
34310 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
34320 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
34330 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34340 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
34350 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
34360 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
34370 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
34380 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
34390 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
343a0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
343b0 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
343c0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
343d0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
343e0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
343f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34400 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
34410 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
34420 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
34430 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
34440 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
34450 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34460 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
34470 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
34480 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
34490 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
344a0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
344b0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
344c0 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
344d0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
344e0 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
344f0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
34500 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
34510 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
34520 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
34530 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
34540 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
34550 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
34560 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
34570 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
34580 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
34590 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
345a0 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
345b0 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
345c0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
345d0 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
345e0 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
345f0 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
34600 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
34610 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
34620 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
34630 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
34640 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
34650 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
34660 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
34670 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
34680 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
34690 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
346a0 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
346b0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
346c0 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
346d0 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
346e0 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
346f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
34700 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
34710 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
34720 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
34730 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
34740 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44  Object.** METHOD
34750 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
34760 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
34770 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
34780 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
34790 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
347a0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
347b0 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
347c0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
347d0 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
347e0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
347f0 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
34800 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
34810 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
34820 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
34830 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
34840 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
34850 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
34860 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
34870 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
34880 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
34890 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
348a0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
348b0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
348c0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
348d0 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
348e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
348f0 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
34900 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
34910 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
34920 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
34930 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
34940 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
34950 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
34960 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34970 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
34980 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
34990 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
349a0 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
349b0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
349c0 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
349d0 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
349e0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
349f0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
34a00 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
34a10 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
34a20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
34a30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
34a40 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
34a50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34a60 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
34a70 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
34a80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
34a90 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
34aa0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
34ab0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
34ac0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
34ad0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
34ae0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
34af0 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
34b00 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
34b10 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
34b20 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
34b30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
34b40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
34b50 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
34b60 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
34b70 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
34b80 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
34b90 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
34ba0 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
34bb0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
34bc0 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
34bd0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
34be0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
34bf0 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
34c00 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
34c10 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
34c20 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
34c30 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
34c40 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
34c50 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
34c60 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
34c70 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
34c80 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
34c90 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
34ca0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
34cb0 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
34cc0 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
34cd0 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
34ce0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
34cf0 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
34d00 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
34d10 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
34d20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
34d30 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
34d40 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
34d50 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
34d60 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
34d70 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
34d80 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
34d90 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
34da0 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
34db0 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
34dc0 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
34dd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34de0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
34df0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
34e00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
34e10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34e20 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
34e30 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
34e40 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
34e50 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
34e60 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
34e70 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
34e80 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
34e90 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
34ea0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
34eb0 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
34ec0 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
34ed0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
34ee0 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
34ef0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
34f00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
34f10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
34f20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
34f30 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
34f40 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
34f50 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
34f60 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
34f70 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
34f80 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
34f90 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
34fa0 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
34fb0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
34fc0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
34fd0 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
34fe0 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
34ff0 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
35000 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
35010 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
35020 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
35030 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
35040 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
35050 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
35060 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
35070 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
35080 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
35090 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
350a0 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
350b0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
350c0 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
350d0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
350e0 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
350f0 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
35100 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
35110 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
35120 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
35130 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
35140 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
35150 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
35160 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
35170 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
35180 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
35190 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
351a0 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
351b0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
351c0 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
351d0 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
351e0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
351f0 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
35200 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
35210 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
35220 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
35230 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
35240 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
35250 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
35260 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
35270 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
35280 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20  arameters.  The 
35290 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
352a0 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61  ld set this para
352b0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c  meter to.** [SQL
352c0 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20  ITE_UTF16LE] if 
352d0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
352e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
352f0 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  kes .** [sqlite3
35300 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
35310 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20  )] on an input, 
35320 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
35330 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d  BE] if the.** im
35340 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
35350 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61  okes [sqlite3_va
35360 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20  lue_text16be()] 
35370 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a  on an input, or.
35380 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
35390 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  ] if [sqlite3_va
353a0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73  lue_text16()] is
353b0 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54   used, or [SQLIT
353c0 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72  E_UTF8].** other
353d0 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65  wise.  ^The same
353e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61   SQL function ma
353f0 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
35400 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
35410 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e  sing.** differen
35420 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  t preferred text
35430 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68   encodings, with
35440 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65   different imple
35450 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a  mentations for.*
35460 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e  * each encoding.
35470 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
35480 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
35490 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
354a0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
354b0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
354c0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
354d0 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
354e0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
354f0 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
35500 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sion..**.** ^The
35510 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
35520 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79  r may optionally
35530 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53   be ORed with [S
35540 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
35550 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  TIC].** to signa
35560 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74  l that the funct
35570 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ion will always 
35580 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
35590 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20  result given.** 
355a0 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20  the same inputs 
355b0 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20  within a single 
355c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
355d0 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  Most SQL functio
355e0 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d  ns are.** determ
355f0 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75  inistic.  The bu
35600 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29  ilt-in [random()
35610 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  ] SQL function i
35620 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
35630 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  a.** function th
35640 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d  at is not determ
35650 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51  inistic.  The SQ
35660 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e  Lite query plann
35670 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a  er is able to.**
35680 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f   perform additio
35690 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  nal optimization
356a0 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74  s on determinist
356b0 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f  ic functions, so
356c0 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b   use.** of the [
356d0 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
356e0 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65  STIC] flag is re
356f0 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20  commended where 
35700 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  possible..**.** 
35710 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
35720 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
35730 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
35740 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
35750 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
35760 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
35770 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
35780 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
35790 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
357a0 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ].)^.**.** ^The 
357b0 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61  sixth, seventh a
357c0 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65  nd eighth parame
357d0 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
357e0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
357f0 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
35800 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
35810 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
35820 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
35830 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
35840 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
35850 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
35860 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
35870 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
35880 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
35890 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
358a0 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70  inters must be p
358b0 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
358c0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
358d0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
358e0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
358f0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
35900 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
35910 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
35920 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
35930 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20  LL pointer must 
35940 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
35950 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20  unc. ^To delete 
35960 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
35970 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
35980 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
35990 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72  ULL pointers for
359a0 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
359b0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73  ion.** callbacks
359c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65  ..**.** ^(If the
359d0 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
359e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
359f0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
35a00 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
35a10 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74   then it is dest
35a20 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61  ructor for the a
35a30 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
35a40 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65  pointer. .** The
35a50 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69   destructor is i
35a60 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
35a70 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
35a80 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62  ted, either by b
35a90 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64  eing.** overload
35aa0 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64  ed or when the d
35ab0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35ac0 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20  on closes.)^.** 
35ad0 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
35ae0 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20  is also invoked 
35af0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  if the call to.*
35b00 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
35b10 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66  _function_v2() f
35b20 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74  ails..** ^When t
35b30 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61  he destructor ca
35b40 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65  llback of the te
35b50 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  nth parameter is
35b60 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20   invoked, it.** 
35b70 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67  is passed a sing
35b80 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
35b90 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  h is a copy of t
35ba0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
35bb0 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ata .** pointer 
35bc0 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69  which was the fi
35bd0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  fth parameter to
35be0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35bf0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  function_v2()..*
35c00 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d  *.** ^It is perm
35c10 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
35c20 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
35c30 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
35c40 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
35c50 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
35c60 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
35c70 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
35c80 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
35c90 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
35ca0 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
35cb0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
35cc0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
35cd0 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
35ce0 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
35cf0 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
35d00 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
35d10 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
35d20 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
35d30 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70   ^A function imp
35d40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
35d50 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
35d60 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
35d70 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
35d80 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
35d90 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
35da0 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
35db0 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20  ative nArg.  ^A 
35dc0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
35dd0 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
35de0 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
35df0 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
35e00 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
35e10 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
35e20 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
35e30 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
35e40 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
35e50 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69  .  .** ^A functi
35e60 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
35e70 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
35e80 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
35e90 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
35ea0 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
35eb0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
35ec0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
35ed0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
35ee0 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
35ef0 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
35f00 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e  .**.** ^Built-in
35f10 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
35f20 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20  e overloaded by 
35f30 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  new application-
35f40 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35f50 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70  s..**.** ^An app
35f60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35f70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
35f80 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
35f90 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
35fa0 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
35fb0 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
35fc0 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
35fd0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
35fe0 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
35ff0 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
36000 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
36010 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
36020 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
36030 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69  is running..*/.i
36040 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36050 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
36060 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
36070 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
36080 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
36090 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
360a0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
360b0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
360c0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
360d0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
360e0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
360f0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
36100 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
36110 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
36120 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
36130 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36140 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
36150 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
36160 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
36170 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
36180 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
36190 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
361a0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
361b0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
361c0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
361d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
361e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
361f0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
36200 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
36210 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
36220 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
36230 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
36240 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
36250 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36260 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
36270 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
36280 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
36290 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
362a0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
362b0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
362c0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
362d0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
362e0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
362f0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
36300 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
36310 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
36320 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
36330 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
36340 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
36350 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  ext*),.  void(*x
36360 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
36370 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36380 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
36390 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
363a0 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
363b0 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
363c0 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
363d0 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
363e0 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
363f0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
36400 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36410 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
36420 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33  1    /* IMP: R-3
36430 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64  7514-35566 */.#d
36440 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
36450 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20  16LE        2   
36460 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31   /* IMP: R-03371
36470 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e  -37637 */.#defin
36480 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
36490 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20          3    /* 
364a0 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31  IMP: R-51971-341
364b0 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  54 */.#define SQ
364c0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
364d0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
364e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
364f0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
36500 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
36510 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65     5    /* Depre
36520 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  cated */.#define
36530 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
36540 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
36550 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36560 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
36570 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36580 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a   Function Flags.
36590 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
365a0 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65  tants may be ORe
365b0 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20  d together with 
365c0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
365d0 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64  UTF8 | preferred
365e0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
365f0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
36600 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
36610 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36620 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ction()], [sqlit
36630 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36640 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
36650 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36660 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  unction_v2()]..*
36670 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36680 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20  _DETERMINISTIC  
36690 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43    0x800../*.** C
366a0 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
366b0 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
366c0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
366d0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
366e0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
366f0 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
36700 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
36710 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
36720 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
36730 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
36740 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
36750 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
36760 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
36770 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
36780 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
36790 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
367a0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65  functions.  To e
367b0 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d  ncourage program
367c0 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  mers to avoid.**
367d0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
367e0 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78  , we will not ex
367f0 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20  plain what they 
36800 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
36810 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
36820 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
36830 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
36840 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
36850 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
36860 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
36870 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
36880 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
36890 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
368a0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
368b0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
368c0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
368d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
368e0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
368f0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
36900 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
36910 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
36920 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
36930 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
36940 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
36950 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
36960 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
36970 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
36980 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
36990 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
369a0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
369b0 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71          void*,sq
369c0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
369d0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
369e0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
369f0 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
36a00 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
36a10 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  lue.**.** The C-
36a20 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
36a30 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
36a40 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
36a50 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
36a60 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
36a70 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
36a80 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
36a90 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
36aa0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
36ab0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20   or aggregate.  
36ac0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
36ad0 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
36ae0 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
36af0 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
36b00 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
36b10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
36b20 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
36b30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
36b40 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
36b50 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
36b60 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
36b70 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
36b80 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
36b90 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
36ba0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
36bb0 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
36bc0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
36bd0 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
36be0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
36bf0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
36c00 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
36c10 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36c20 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
36c30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
36c40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
36c50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
36c60 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
36c70 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
36c80 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
36c90 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
36ca0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
36cb0 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
36cc0 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
36cd0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36ce0 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
36cf0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
36d00 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
36d10 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
36d20 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
36d30 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
36d40 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
36d50 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
36d60 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
36d70 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
36d80 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
36d90 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
36da0 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
36db0 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74   that these rout
36dc0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
36dd0 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
36de0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36df0 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
36e00 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
36e10 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
36e20 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
36e30 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
36e40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36e50 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36e60 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
36e70 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
36e80 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
36e90 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
36ea0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
36eb0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
36ec0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
36ed0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
36ee0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36ef0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
36f00 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
36f10 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
36f20 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
36f30 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
36f40 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
36f50 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
36f60 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
36f70 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
36f80 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
36f90 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
36fa0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
36fb0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
36fc0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
36fd0 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
36fe0 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
36ff0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
37000 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
37010 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
37020 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
37030 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
37040 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
37050 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
37060 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
37070 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
37080 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
37090 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
370a0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
370b0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
370c0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
370d0 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
370e0 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
370f0 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
37100 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
37110 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
37120 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
37130 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
37140 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
37150 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
37160 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
37170 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
37180 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
37190 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
371a0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
371b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
371c0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
371d0 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
371e0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
371f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
37200 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
37210 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
37220 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
37230 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
37240 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
37250 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
37260 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
37270 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
37280 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
37290 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
372a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
372b0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
372c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
372d0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
372e0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
372f0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
37300 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
37310 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
37320 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
37330 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
37340 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
37350 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37360 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
37370 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
37380 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
37390 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
373a0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
373b0 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
373c0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
373d0 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
373e0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
373f0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
37400 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37410 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37420 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
37430 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37440 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
37450 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
37460 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37470 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
37480 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
37490 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
374a0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
374b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
374c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
374d0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
374e0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
374f0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
37500 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
37510 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
37520 52 45 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65  REF: Finding The
37530 20 53 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20   Subtype Of SQL 
37540 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
37550 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
37560 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
37570 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28  3_value_subtype(
37580 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  V) function retu
37590 72 6e 73 20 74 68 65 20 73 75 62 74 79 70 65 20  rns the subtype 
375a0 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69  for.** an [appli
375b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
375c0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67  QL function] arg
375d0 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75  ument V.  The su
375e0 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  btype.** informa
375f0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
37600 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74   to pass a limit
37610 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  ed amount of con
37620 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  text from.** one
37630 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
37640 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74   another.  Use t
37650 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
37660 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a  lt_subtype()].**
37670 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20   routine to set 
37680 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 20  the subtype for 
37690 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
376a0 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74   of an SQL funct
376b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
376c0 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f  e makes no use o
376d0 66 20 73 75 62 74 79 70 65 20 69 74 73 65 6c 66  f subtype itself
376e0 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73  .  It merely pas
376f0 73 65 73 20 74 68 65 20 73 75 62 74 79 70 65 0a  ses the subtype.
37700 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75  ** from the resu
37710 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69  lt of one [appli
37720 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
37730 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74  QL function] int
37740 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f  o the.** input o
37750 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e  f another..*/.un
37760 73 69 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74  signed int sqlit
37770 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65  e3_value_subtype
37780 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37790 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
377a0 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65  F: Copy And Free
377b0 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d   SQL Values.** M
377c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76  ETHOD: sqlite3_v
377d0 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  alue.**.** ^The 
377e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
377f0 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d  p(V) interface m
37800 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
37810 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
37820 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61  e].** object D a
37830 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
37840 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70  nter to that cop
37850 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  y.  ^The [sqlite
37860 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65  3_value] returne
37870 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65  d.** is a [prote
37880 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
37890 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20  ue] object even 
378a0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
378b0 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  not..** ^The sql
378c0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
378d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
378e0 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73  rns NULL if V is
378f0 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a   NULL or if a.**
37900 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
37910 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  on fails..**.** 
37920 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
37930 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72  ue_free(V) inter
37940 66 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73  face frees an [s
37950 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37960 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73  ject.** previous
37970 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
37980 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37990 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69  dup()].  ^If V i
379a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
379b0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
379c0 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69  _value_free(V) i
379d0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
379e0 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76  op..*/.sqlite3_v
379f0 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61  alue *sqlite3_va
37a00 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71  lue_dup(const sq
37a10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
37a20 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  oid sqlite3_valu
37a30 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76  e_free(sqlite3_v
37a40 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
37a50 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
37a60 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
37a70 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45  on Context.** ME
37a80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
37a90 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
37aa0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
37ab0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
37ac0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
37ad0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
37ae0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
37af0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
37b00 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
37b10 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
37b20 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
37b30 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
37b40 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
37b50 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
37b60 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
37b70 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
37b80 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
37b90 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
37ba0 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
37bb0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
37bc0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
37bd0 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
37be0 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
37bf0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
37c00 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
37c10 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37c20 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
37c30 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
37c40 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
37c50 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
37c60 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
37c70 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37c80 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
37c90 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
37ca0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
37cb0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
37cc0 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
37cd0 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
37ce0 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
37cf0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
37d00 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
37d10 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
37d20 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
37d30 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
37d40 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
37d50 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
37d60 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
37d70 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
37d80 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
37d90 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
37da0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
37db0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
37dc0 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
37dd0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
37de0 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
37df0 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
37e00 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
37e10 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
37e20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37e30 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37e40 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
37e50 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
37e60 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66  inter .** when f
37e70 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e  irst called if N
37e80 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72   is less than or
37e90 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
37ea0 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a  r if a memory.**
37eb0 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
37ec0 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
37ed0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
37ee0 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
37ef0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
37f00 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
37f10 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
37f20 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
37f30 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
37f40 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
37f50 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
37f60 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
37f70 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
37f80 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37f90 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
37fa0 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
37fb0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
37fc0 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
37fd0 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
37fe0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
37ff0 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74  ion.)^  Within t
38000 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
38010 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d  ck, it is custom
38020 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d  ary to set.** N=
38030 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71  0 in calls to sq
38040 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
38050 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20  context(C,N) so 
38060 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e  that no .** poin
38070 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tless memory all
38080 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a  ocations occur..
38090 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75  **.** ^SQLite au
380a0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
380b0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
380c0 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71  ocated by .** sq
380d0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
380e0 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74  context() when t
380f0 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65  he aggregate que
38100 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
38110 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
38120 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
38130 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
38140 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
38150 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
38160 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
38170 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
38180 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
38190 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20  xStep or xFinal 
381a0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
381b0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
381c0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
381d0 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
381e0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
381f0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
38200 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
38210 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
38220 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
38230 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
38240 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
38250 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
38260 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
38270 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
38280 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
38290 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
382a0 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
382b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
382c0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
382d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
382e0 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
382f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
38300 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
38310 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
38320 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
38330 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
38340 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
38350 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
38360 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
38370 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
38380 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
38390 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
383a0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
383b0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
383c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
383d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
383e0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
383f0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
38400 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
38410 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
38420 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
38430 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
38440 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
38450 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
38460 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
38470 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
38480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
38490 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
384a0 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
384b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
384c0 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
384d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
384e0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
384f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
38500 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
38510 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
38520 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
38530 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
38540 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
38550 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
38560 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
38570 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
38580 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
38590 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
385a0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
385b0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
385c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
385d0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
385e0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
385f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
38600 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
38610 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
38620 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
38630 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
38640 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ata.** METHOD: s
38650 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
38660 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
38670 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
38680 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
38690 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
386a0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
386b0 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
386c0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
386d0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
386e0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
386f0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
38700 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
38710 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
38720 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
38730 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
38740 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
38750 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
38760 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
38770 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
38780 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
38790 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68   where this migh
387a0 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69  t be useful is i
387b0 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  n a regular-expr
387c0 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a  ession matching.
387d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
387e0 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
387f0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
38800 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
38810 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  be stored as.** 
38820 6d 65 74 61 64