/ Hex Artifact Content
Login

Artifact 723107d97f2345a7c103632169dc61366121c4ab65d75a7d83c6dc0e5bbe5ca4:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 20  -in (UTC) and a 
1090: 53 48 41 31 0a 2a 2a 20 6f 72 20 53 48 41 33 2d  SHA1.** or SHA3-
10a0: 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 65 20  256 hash of the 
10b0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
10c0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
10d0: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
10e0: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
10f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1100: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1110: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1120: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1130: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1140: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1150: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
1170: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1190: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
11a0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
11b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11c0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
11d0: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
11e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11f0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1200: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1210: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1220: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71  lite3_version sq
1230: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
1240: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
1250: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
1260: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1270: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
1280: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
1290: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
12a0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
12b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
12c0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
12d0: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
12e0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
12f0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1300: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1310: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
1320: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
1330: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
1340: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
1350: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
1360: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
1370: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
1380: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
1390: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
13a0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
13b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
13c0: 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75  r, and thus ensu
13d0: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
13e0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
13f0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
1400: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
1410: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
1420: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1430: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
1440: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
1450: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
1460: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1470: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
1480: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1490: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
14a0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
14b0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
14c0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
14d0: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
14e0: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
14f0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1500: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
1520: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1530: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
1540: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
1550: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
1560: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
1570: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1580: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1590: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
15a0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
15b0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
15c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
15d0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
15e0: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
15f0: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1600: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
1610: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
1620: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
1630: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
1640: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1650: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
1660: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
1670: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
1680: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1690: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
16a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
16b0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
16c0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
16d0: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
16e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
16f0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
1700: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1710: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
1720: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
1730: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
1740: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
1750: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1760: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
1770: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1780: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1790: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
17a0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
17b0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
17c0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
17d0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
17e0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
17f0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f  ersion(void);.co
1800: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1810: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29  3_sourceid(void)
1820: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  ;.int sqlite3_li
1830: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1840: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1850: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1860: 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61   Library Compila
1870: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61  tion Options Dia
1880: 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e  gnostics.**.** ^
1890: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
18a0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
18b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
18c0: 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64  s 0 or 1 .** ind
18d0: 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20  icating whether 
18e0: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70  the specified op
18f0: 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64  tion was defined
1900: 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20   at .** compile 
1910: 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49  time.  ^The SQLI
1920: 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62  TE_ prefix may b
1930: 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1940: 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61  he .** option na
1950: 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c  me passed to sql
1960: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1970: 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a  on_used().  .**.
1980: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
19a0: 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c  t() function all
19b0: 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a  ows iterating.**
19c0: 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f   over the list o
19d0: 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77  f options that w
19e0: 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63  ere defined at c
19f0: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a  ompile time by.*
1a00: 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20  * returning the 
1a10: 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d  N-th compile tim
1a20: 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e  e option string.
1a30: 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f    ^If N is out o
1a40: 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69  f range,.** sqli
1a50: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1a60: 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20  n_get() returns 
1a70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1a80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a   ^The SQLITE_ .*
1a90: 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74  * prefix is omit
1aa0: 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72  ted from any str
1ab0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1ac0: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d   .** sqlite3_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ae0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74  ..**.** ^Support
1af0: 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73   for the diagnos
1b00: 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71  tic functions sq
1b10: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1b20: 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e  ion_used().** an
1b30: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  d sqlite3_compil
1b40: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61  eoption_get() ma
1b50: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20  y be omitted by 
1b60: 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a  specifying the .
1b70: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ** [SQLITE_OMIT_
1b80: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1b90: 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63  AGS] option at c
1ba0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a  ompile time..**.
1bb0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c  ** See also: SQL
1bc0: 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69   functions [sqli
1bd0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1be0: 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1bf0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1c00: 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64  ption_get()] and
1c10: 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70   the [compile_op
1c20: 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a  tions pragma]..*
1c30: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1c40: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1c50: 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71  ION_DIAGS.int sq
1c60: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c70: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
1c80: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
1c90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1ca0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1cb0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1cc0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cd0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1ce0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cf0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1d00: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d10: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d30: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d40: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d50: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d60: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d70: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d80: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d90: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1da0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1db0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1dc0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1dd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1de0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1df0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1e00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1e10: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e20: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e30: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e40: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e50: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e60: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e70: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e80: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e90: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1ea0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1eb0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ec0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1ed0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ee0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ef0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1f00: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1f10: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f20: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f30: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f40: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f50: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f60: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f70: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f80: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f90: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1fa0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1fb0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fc0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fd0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fe0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1ff0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
2000: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
2010: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2020: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2030: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2040: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2050: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2060: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2070: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2080: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2090: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
20a0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
20b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20c0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20d0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20e0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20f0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2100: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2110: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2120: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2130: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2140: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2150: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2160: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2170: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2180: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2190: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
21a0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
21b0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21c0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21e0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21f0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2200: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2210: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2220: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2230: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2240: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2250: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2260: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2270: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2280: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2290: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
22a0: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
22b0: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22c0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22d0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22e0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22f0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2300: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2310: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2320: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2330: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2340: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2350: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2360: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2370: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2380: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2390: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
23a0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
23b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
23d0: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
23e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
23f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2400: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2410: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2420: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
2430: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2440: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2450: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2460: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2470: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2480: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2490: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
24a0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
24b0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
24c0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
24d0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
24e0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
24f0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2500: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2510: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2520: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2530: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2540: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2550: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2560: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2570: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2580: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2590: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
25a0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
25b0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
25c0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
25d0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
25e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
25f0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2600: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2620: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2630: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2640: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2650: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2660: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2680: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2690: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
26a0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
26b0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
26c0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
26d0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
26e0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
26f0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
2700: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2710: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2720: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2730: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2740: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2750: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2760: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2770: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2780: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2790: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
27a0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
27b0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
27c0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
27d0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
27e0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
27f0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2800: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2810: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2820: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2830: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2840: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2850: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2860: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2870: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2880: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2890: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
28a0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
28b0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
28c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
28d0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
28e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
28f0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2900: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2910: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2920: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2930: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2940: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2950: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2960: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2970: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2980: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2990: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
29a0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
29b0: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
29c0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
29d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
29e0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
29f0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2a00: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2a10: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2a20: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2a30: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2a40: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2a50: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2a60: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2a70: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2a80: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2a90: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2aa0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2ab0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2ac0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2ad0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ae0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2af0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2b00: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2b10: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2b20: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2b30: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2b40: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2b50: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2b60: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2b70: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2b80: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2b90: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2ba0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2bb0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2bc0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2bd0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2bf0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2c00: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2c10: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2c20: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2c40: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2c50: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2c60: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2c70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2c80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2c90: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2ca0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2cb0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2cc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2cd0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ce0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2cf0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2d00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2d10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2d20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2d30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2d40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2d50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2d60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2d70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2d90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2da0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2db0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2dc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2dd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2de0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2df0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2e00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2e10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2e20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2e30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2e40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2e50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
2e60: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2e70: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
2e80: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2e90: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
2ea0: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
2eb0: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
2ec0: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2ed0: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
2ee0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
2ef0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2f00: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2f10: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
2f20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
2f30: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
2f40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
2f50: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2f60: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
2f70: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
2f80: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
2f90: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
2fa0: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
2fb0: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
2fc0: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
2fd0: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
2fe0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
2ff0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
3000: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
3010: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
3020: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
3030: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3040: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3050: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3060: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3070: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3080: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3090: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
30a0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30b0: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
30c0: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
30d0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
30e0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
30f0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
3100: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
3110: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
3120: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
3130: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3140: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3150: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3160: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3170: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3180: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3190: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
31a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31b0: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
31c0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
31d0: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
31e0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
31f0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
3200: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
3210: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
3220: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
3230: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3240: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3250: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3260: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3270: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3280: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3290: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
32a0: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
32b0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
32c0: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
32d0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
32e0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
32f0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
3300: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
3310: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
3320: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
3330: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3340: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3350: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3360: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3370: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3380: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3390: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
33a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
33b0: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
33c0: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
33d0: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
33e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
33f0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
3400: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
3410: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
3420: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
3430: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74  ss no-op..*/.int
3440: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
3450: 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71  qlite3*);.int sq
3460: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73  lite3_close_v2(s
3470: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
3480: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
3490: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
34a0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
34b0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
34c0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
34d0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
34e0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
34f0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
3500: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
3510: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
3520: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
3530: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3540: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
3550: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
3560: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
3570: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  ion Interface.**
3580: 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
3590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35a0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
35b0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
35c0: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
35d0: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
35e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
35f0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3610: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
3620: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
3630: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
3640: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
3650: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
3660: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
3670: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
3680: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
3690: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
36a0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
36b0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
36c0: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
36d0: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
36e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
36f0: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
3700: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
3710: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
3720: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
3730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
3740: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
3750: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
3760: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3770: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
3780: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3790: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
37a0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
37b0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
37c0: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
37d0: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
37e0: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
37f0: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
3800: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
3810: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3820: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3830: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
3840: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
3850: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
3860: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
3870: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
3880: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
38b0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
38c0: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
38d0: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
38e0: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
38f0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
3900: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
3910: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
3920: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3930: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
3940: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
3950: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
3960: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
3970: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
3980: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
3990: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
39a0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
39b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
39c0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
39d0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
39e0: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
39f0: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
3a00: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3a10: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3a20: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
3a30: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
3a40: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3a50: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
3a60: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
3a70: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
3a80: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
3a90: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
3aa0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
3ab0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
3ac0: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
3ad0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3ae0: 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  of.** sqlite3_ex
3af0: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65  ec() after the e
3b00: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
3b10: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ing is no longer
3b20: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20   needed..** ^If 
3b30: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3b40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3b50: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  c() is not NULL 
3b60: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  and no errors.**
3b70: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c   occur, then sql
3b80: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73  ite3_exec() sets
3b90: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   the pointer in 
3ba0: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65  its 5th paramete
3bb0: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66  r to.** NULL bef
3bc0: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
3bd0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69  *.** ^If an sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3bf0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
3c00: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65  zero, the sqlite
3c10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74  3_exec().** rout
3c20: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
3c30: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74  TE_ABORT without
3c40: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61   invoking the ca
3c50: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64  llback again and
3c60: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e  .** without runn
3c70: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65  ing any subseque
3c80: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
3c90: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e  s..**.** ^The 2n
3ca0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3cb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3cc0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3cd0: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  on is the.** num
3ce0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3cf0: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e  n the result.  ^
3d00: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  The 3rd argument
3d10: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3d20: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61  exec().** callba
3d30: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
3d40: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3d50: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61  rings obtained a
3d60: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  s if from.** [sq
3d70: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
3d80: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61  t()], one for ea
3d90: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20  ch column.  ^If 
3da0: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a  an element of a.
3db0: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73  ** result row is
3dc0: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
3dd0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72  orresponding str
3de0: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ing pointer for 
3df0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3e00: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3e10: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3e20: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3e30: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73  ment to the.** s
3e40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3e50: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3e60: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3e70: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
3e80: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65  each.** entry re
3e90: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d  presents the nam
3ea0: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69  e of correspondi
3eb0: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ng result column
3ec0: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20   as obtained.** 
3ed0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
3ee0: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
3ef0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20  .** ^If the 2nd 
3f00: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3f10: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61  ite3_exec() is a
3f20: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61   NULL pointer, a
3f30: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
3f40: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
3f50: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61  or a pointer tha
3f60: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20  t contains only 
3f70: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f  whitespace and/o
3f80: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e  r .** SQL commen
3f90: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20  ts, then no SQL 
3fa0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
3fb0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3fc0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
3fd0: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  not changed..**.
3fe0: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a  ** Restrictions:
3ff0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
4000: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4010: 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20  ion must ensure 
4020: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72  that the 1st par
4030: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4040: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20  3_exec().**     
4050: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20   is a valid and 
4060: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
4070: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c  onnection]..** <
4080: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4090: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ion must not clo
40a0: 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  se the [database
40b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
40c0: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
40d0: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
40e0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40f0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4100: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4110: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
4120: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
4130: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
4140: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
4150: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
4160: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
4170: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
4180: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
4190: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
41a0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
41b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
41c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
41d0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
4200: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
4210: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
4220: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4240: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
4250: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
4260: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
4270: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
4280: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
4290: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
42a0: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
42d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
42e0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
42f0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4310: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
4320: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
4330: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
4340: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
4350: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4360: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65   {result code de
4370: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  finitions}.**.**
4380: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
4390: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
43a0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
43b0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
43c0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
43d0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
43e0: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
43f0: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4400: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4410: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4420: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4430: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4440: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e  See also: [exten
4450: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4460: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a  definitions].*/.
4470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4480: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20  K           0   
4490: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65  /* Successful re
44a0: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e  sult */./* begin
44b0: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f  ning-of-error-co
44c0: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  des */.#define S
44d0: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
44e0: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
44f0: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
4500: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4510: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
4520: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e  AL     2   /* In
4530: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72  ternal logic err
4540: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a  or in SQLite */.
4550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4560: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20  ERM         3   
4570: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73  /* Access permis
4580: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  sion denied */.#
4590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
45a0: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f  ORT        4   /
45b0: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  * Callback routi
45c0: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20  ne requested an 
45d0: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65  abort */.#define
45e0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20   SQLITE_BUSY    
45f0: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20       5   /* The 
4600: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
4610: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4620: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
4630: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20         6   /* A 
4640: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74  table in the dat
4650: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20  abase is locked 
4660: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4670: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37  E_NOMEM        7
4680: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29     /* A malloc()
4690: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69   failed */.#defi
46a0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
46b0: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74  LY     8   /* At
46c0: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61  tempt to write a
46d0: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61   readonly databa
46e0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
46f0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20  LITE_INTERRUPT  
4700: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69    9   /* Operati
4710: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79  on terminated by
4720: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
4730: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pt()*/.#define S
4740: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20  QLITE_IOERR     
4750: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b    10   /* Some k
4760: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20  ind of disk I/O 
4770: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a  error occurred *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4790: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20  _CORRUPT     11 
47a0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
47b0: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20  e disk image is 
47c0: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65  malformed */.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46  fine SQLITE_NOTF
47e0: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20  OUND    12   /* 
47f0: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69  Unknown opcode i
4800: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  n sqlite3_file_c
4810: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66  ontrol() */.#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
4830: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
4840: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
4850: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
4860: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
4880: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
4890: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
48a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
48b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
48c0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
48d0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c     /* Database l
48e0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
48f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4900: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4910: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4920: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4940: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4950: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4960: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4980: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4990: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
49a0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
49b0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49c0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49d0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49e0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49f0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4a10: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a20: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a30: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a40: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a50: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a60: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a70: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a80: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a90: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4aa0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4ab0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4ac0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ad0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ae0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4af0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4b10: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b20: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4b30: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4b40: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4b50: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4b60: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4b70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4b80: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4b90: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4ba0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4bb0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4bc0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4bd0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4be0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4bf0: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20  ITE_NOTICE      
4c00: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61  27   /* Notifica
4c10: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74  tions from sqlit
4c20: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
4c30: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
4c40: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57  NG     28   /* W
4c50: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c  arnings from sql
4c60: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
4c80: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
4c90: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ca0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
4cb0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
4cc0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
4cd0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
4ce0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
4cf0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
4d00: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
4d10: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
4d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
4d30: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
4d40: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4d50: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4d60: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4d70: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  ons}.**.** In it
4d80: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
4d90: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
4da0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
4db0: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e  urn one of 30 in
4dc0: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74  teger.** [result
4dd0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4de0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4df0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
4e00: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
4e10: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
4e20: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4e30: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4e40: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4e50: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4e60: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4e70: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4e80: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4e90: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4ea0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4eb0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4ec0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4ed0: 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 38  .8 [dateof:3.3.8
4ee0: 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 29 20  ].** and later) 
4ef0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4f00: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4f10: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4f20: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4f30: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4f40: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4f50: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4f60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f70: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4f80: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4f90: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4fa0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4fb0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4fc0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4fd0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4fe0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4ff0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
5000: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
5010: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
5020: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
5030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
5040: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
5050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5060: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5070: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5080: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5090: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
50b0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
50c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50e0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5100: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5110: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5120: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5130: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5140: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
51a0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
51b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
51c0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5220: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5240: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5260: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5270: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5280: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5290: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52a0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
52b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52c0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5320: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5340: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5360: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5380: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53a0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
53b0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
53c0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53e0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5400: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5420: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5440: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5460: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5480: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54a0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
54b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54c0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54e0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5500: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5520: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5540: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5560: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5580: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55a0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
55b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55c0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55e0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
55f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5600: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5620: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5640: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5660: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5680: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56a0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
56b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56c0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
56d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56e0: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
56f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5700: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5720: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5740: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5750: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5760: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5770: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5780: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
57a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
57b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
57c0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
57d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
57e0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
57f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5800: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5820: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5840: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5860: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5870: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58a0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
58b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
58d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
58f0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5900: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5910: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5930: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5940: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5950: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5970: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5990: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
59a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
59b0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
59c0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59d0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
59e0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
59f0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5a00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5a10: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5a30: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5a50: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5a70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
5a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5ac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5b00: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b60: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b80: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5ba0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5c10: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c30: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c70: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c90: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5cb0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5d20: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5d40: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d60: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5da0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5dc0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5de0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5df0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5e00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5e10: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5e30: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5e60: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5e70: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5e80: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5e90: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5ea0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5eb0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5ec0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5ed0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5ee0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5ef0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5f00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5f10: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5f20: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5f30: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5f40: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5f50: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5f60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f70: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5f80: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5f90: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fa0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fc0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5fd0: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5fe0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5ff0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6010: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
6020: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
6030: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6040: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6060: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
6070: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
6080: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60a0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
60b0: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
60c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
60f0: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6100: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
6130: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
6140: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6150: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6170: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
6180: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6190: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
61a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61c0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
61d0: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
61e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6200: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6210: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6220: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6240: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
6250: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
6260: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6280: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6290: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
62a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62c0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
62d0: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
62e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6300: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6310: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6320: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
6350: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
6360: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6380: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6390: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
63a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63d0: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
63e0: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
63f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6400: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6420: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
6430: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
6440: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6450: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6470: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
6480: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6490: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
64a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
64b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
64c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
64d0: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
64e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
64f0: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
6500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6510: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
6520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6530: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
6540: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
6550: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6560: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
6570: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6580: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6590: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
65a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
65b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
65c0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
65d0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
65e0: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
65f0: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
6600: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
6610: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
6620: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
6630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6640: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
6650: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6660: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
6670: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6680: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
6690: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
66a0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
66b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
66c0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
66d0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
66e0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
66f0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6700: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6710: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6720: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
6730: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
6740: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
6750: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6760: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6770: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
6780: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
6790: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
67a0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
67b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
67c0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
67d0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
67e0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
67f0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6800: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6810: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6820: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
6830: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6840: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
6850: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
6860: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
6870: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
6880: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
6890: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
68a0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
68b0: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
68c0: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
68d0: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
68e0: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
68f0: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
6900: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
6910: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
6920: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
6930: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
6940: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
6950: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
6960: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
6970: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
6980: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
6990: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
69a0: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
69b0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
69c0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
69d0: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c  _WHEN_OPEN.** fl
69e0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
69f0: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
6a00: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
6a10: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
6a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6a30: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
6a40: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
6a50: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
6a60: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
6a70: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
6a80: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
6a90: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
6aa0: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
6ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
6ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6ae0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b00: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b50: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b70: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6b80: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ba0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6bc0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6be0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6bf0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c10: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c30: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6c40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6c50: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6c60: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c80: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
6c90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6ca0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6cb0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6cc0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
6cd0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
6ce0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6cf0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6d00: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d20: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6d30: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6d40: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6d50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6d60: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6d70: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
6d80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6d90: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
6da0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6db0: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
6dc0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6dd0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6de0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6df0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6e00: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6e10: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6e20: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6e30: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6e40: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6e50: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6e60: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6e70: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6e90: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6ea0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6eb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6ec0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6ed0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6ee0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f00: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6f10: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6f30: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6f40: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6f50: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6f60: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6f70: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6f80: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6f90: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6fa0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6fb0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
6fc0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6fd0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6fe0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6ff0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
7000: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
7010: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7020: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
7030: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
7040: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
7050: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
7060: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
7070: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
7080: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
7090: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
70a0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
70b0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
70c0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
70d0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
70e0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
70f0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
7100: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
7110: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
7120: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
7130: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7140: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
7150: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
7160: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
7170: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
7180: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
7190: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
71a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
71b0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
71c0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
71d0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
71e0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
71f0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
7200: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
7210: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
7220: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
7230: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
7240: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
7250: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
7260: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
7270: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
7280: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
7290: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
72a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
72b0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
72c0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
72d0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
72e0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
72f0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
7300: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
7310: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
7320: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
7330: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
7340: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
7350: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
7360: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
7370: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
7380: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
7390: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
73a0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
73b0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
73c0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
73d0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
73e0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
73f0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
7400: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
7410: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
7420: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
7430: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
7440: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
7450: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7460: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
7470: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
7480: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7490: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
74a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
74b0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
74c0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
74d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
74e0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
74f0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
7500: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
7510: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
7520: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
7530: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
7540: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
7550: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
7560: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
7570: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
7580: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
7590: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
75a0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
75b0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
75c0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
75d0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
75e0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
75f0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
7600: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
7610: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7620: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
7630: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
7640: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
7650: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
7660: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
7670: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
7680: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
7690: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
76a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
76b0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
76c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
76d0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
76e0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
76f0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
7700: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7710: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7720: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
7730: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
7740: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
7750: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
7760: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7770: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
7780: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
7790: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
77a0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
77b0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
77c0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
77d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
77e0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
77f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
7800: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
7810: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7820: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7830: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
7840: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
7850: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
7860: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
7870: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
7880: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7890: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
78a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
78b0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
78c0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
78d0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
78e0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
78f0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
7900: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7910: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7920: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7930: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7940: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7950: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7960: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
7970: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
7980: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
7990: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
79a0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
79b0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
79c0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
79d0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
79e0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
79f0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7a00: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7a10: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7a20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7a30: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7a40: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7a50: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7a60: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
7a70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
7a80: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
7a90: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
7aa0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
7ab0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
7ac0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
7ad0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7ae0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7af0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7b00: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7b10: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7b20: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7b30: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7b40: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7b50: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7b60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7b70: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7b80: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7b90: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7ba0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7bb0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7bc0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7be0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7bf0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7c00: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7c10: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7c20: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7c30: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7c40: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7c50: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7c60: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7c70: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7c80: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7c90: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7ca0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
7cb0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
7cc0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7cd0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7ce0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7cf0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7d00: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7d10: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7d20: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7d30: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7d40: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7d50: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7d60: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7d70: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7d80: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7d90: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7da0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
7db0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
7dc0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7dd0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7de0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7df0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7e00: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7e10: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7e20: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7e30: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7e40: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7e50: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7e60: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7e70: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7e80: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7e90: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7ea0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
7eb0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
7ec0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7ed0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7ee0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7ef0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7f00: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7f10: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7f20: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7f30: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7f40: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7f50: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7f60: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7f70: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7f80: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7f90: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7fa0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
7fb0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
7fc0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7fd0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7fe0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7ff0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
8000: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
8010: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
8020: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
8030: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
8040: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8050: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f  odes | list of o
8060: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
8070: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
8080: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
8090: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
80a0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
80b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
80c0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
80d0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
80e0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
80f0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
8100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
8110: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
8120: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
8130: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
8140: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
8150: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
8160: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
8170: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
8180: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
8190: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
81a0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
81b0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
81c0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
81d0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
81e0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
81f0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
8200: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
8210: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
8220: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
8230: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
8240: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8250: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
8260: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
8270: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
8280: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
8290: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
82a0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
82b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
82d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
82f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8300: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
8310: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
8330: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8340: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
8350: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8360: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
8370: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8380: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
8390: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
83b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
83c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
83d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
83e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
83f0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
8400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8410: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENTIAL].** <li> 
8420: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e  [SQLITE_IOCAP_UN
8430: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
8440: 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  PEN].** <li> [SQ
8450: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
8460: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a  SAFE_OVERWRITE].
8470: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8480: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
8490: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
84a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
84b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
84c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
84d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
84e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
84f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8500: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8510: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8520: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8530: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8540: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8550: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8560: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8570: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8580: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8590: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
85a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
85b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
85c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
85d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
85e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
85f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8600: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8610: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8620: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8630: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8640: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8650: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8660: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8670: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8680: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8690: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
86a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
86b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
86c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
86d0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
86e0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
86f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8700: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8710: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8720: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8730: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8740: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8750: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8760: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8770: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8780: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8790: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
87a0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
87b0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
87c0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
87d0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
87e0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
87f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8810: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8820: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8830: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8840: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8850: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8860: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8880: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8890: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
88a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
88b0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
88c0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
88d0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
88e0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
88f0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8900: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8910: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8920: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8930: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8940: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8950: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8960: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8970: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8980: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8990: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
89a0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
89b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
89c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
89d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
89e0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
89f0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8a00: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8a10: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8a20: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8a30: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8a40: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8a50: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8a60: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8a70: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8a80: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8a90: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8aa0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8ab0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8ac0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8ad0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8ae0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8af0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8b00: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8b10: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8b20: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8b30: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8b40: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8b50: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8b60: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8b70: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8b80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8b90: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8ba0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8bb0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8bc0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8bd0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8be0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8bf0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8c00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8c10: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8c20: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8c30: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8c40: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8c50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8c60: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8c70: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8c80: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8c90: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8ca0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8cb0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8cc0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8cd0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8ce0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8cf0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8d00: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8d10: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8d20: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8d30: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8d40: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8d50: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8d60: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8d70: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8d80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8d90: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8da0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8db0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8dc0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8dd0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8de0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8df0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8e00: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8e10: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8e20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8e30: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8e40: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8e50: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8e60: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8e70: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8e80: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8e90: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8ea0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8eb0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8ec0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ed0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8ee0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8ef0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8f00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8f10: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8f30: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8f40: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8f50: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8f60: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8f70: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8f80: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8f90: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8fa0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8fb0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8fc0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8fd0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8fe0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8ff0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
9000: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9010: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
9020: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9030: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
9040: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
9050: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
9060: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
9070: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
9080: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
9090: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
90a0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
90b0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
90c0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
90d0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
90e0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
90f0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
9100: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
9110: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
9120: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9130: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
9140: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
9150: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
9160: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
9170: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
9180: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
9190: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
91a0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
91b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
91c0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
91d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
91e0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
91f0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9200: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9210: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9220: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9230: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9240: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9250: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9260: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9270: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9280: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
9290: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
92a0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
92b0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
92c0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
92d0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
92e0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
92f0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9300: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9310: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9320: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9330: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9340: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9350: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9360: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9370: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9380: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9390: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
93a0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
93b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
93c0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
93d0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
93e0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
93f0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9400: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9410: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9420: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9430: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9440: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9450: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9460: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9470: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9480: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9490: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
94a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
94b0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
94c0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
94d0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
94e0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
94f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9500: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9510: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
9520: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
9530: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
9540: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
9550: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
9560: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
9570: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
9580: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
9590: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
95a0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
95b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
95c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
95d0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
95e0: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
95f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9600: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
9610: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9620: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
9630: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
9640: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9650: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
9660: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
9670: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
9680: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9690: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
96a0: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
96b0: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
96c0: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
96d0: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
96e0: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
96f0: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
9700: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
9710: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
9720: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
9730: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
9740: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
9750: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
9760: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
9770: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
9780: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
9790: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
97a0: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
97b0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
97c0: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
97d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
97e0: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
97f0: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
9800: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
9810: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
9820: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
9830: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
9840: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
9850: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
9860: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
9870: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
9880: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
9890: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
98a0: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
98b0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
98c0: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
98d0: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
98e0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
98f0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9900: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9910: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9920: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
9930: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
9940: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9950: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9960: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9970: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9980: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9990: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
99a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
99b0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
99c0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
99d0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
99e0: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
99f0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9a00: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
9a10: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
9a20: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
9a30: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
9a40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
9a50: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
9a60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
9a70: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
9a80: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9a90: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9aa0: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9ab0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
9ac0: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
9ad0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9ae0: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9af0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9b00: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
9b10: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9b20: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9b30: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9b40: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9b50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b60: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9b70: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9b80: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9b90: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9ba0: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9bb0: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9bc0: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9bd0: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9be0: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
9bf0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
9c00: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
9c10: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
9c20: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
9c30: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
9c40: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
9c50: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
9c60: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9c70: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9c80: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9c90: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9ca0: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9cb0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9cc0: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9cd0: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9ce0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
9cf0: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
9d00: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
9d10: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
9d20: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
9d30: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
9d40: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
9d50: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
9d60: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9d70: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9d80: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9d90: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9da0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9db0: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9dc0: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9dd0: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9de0: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
9df0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
9e00: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9e10: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
9e20: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
9e30: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
9e40: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
9e50: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
9e60: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
9e70: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
9e80: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
9e90: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
9ea0: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
9eb0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
9ec0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
9ed0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
9ee0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
9ef0: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
9f00: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
9f10: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
9f20: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
9f30: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
9f40: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
9f50: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
9f60: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
9f70: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
9f80: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
9f90: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
9fa0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9fb0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9fc0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9fd0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9fe0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
9ff0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
a000: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
a010: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
a020: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
a030: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
a040: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
a050: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
a060: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
a070: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
a080: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
a090: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
a0a0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
a0b0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
a0c0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
a0d0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
a0e0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
a0f0: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
a100: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
a110: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
a120: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
a130: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
a140: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
a150: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
a160: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
a170: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
a180: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
a190: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a1a0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a1b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a1c0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a1d0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a1e0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
a1f0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a200: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
a210: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
a220: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
a230: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
a240: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a250: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a260: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a270: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a280: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a290: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a2a0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a2b0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a2c0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
a2d0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
a2e0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
a2f0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
a300: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a310: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a320: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a330: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a340: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
a350: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
a360: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a370: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a380: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a390: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a3a0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a3b0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a3c0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a3d0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a3e0: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
a3f0: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
a400: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
a410: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
a420: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
a430: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
a440: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
a450: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
a460: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
a470: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
a480: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
a490: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a4a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a4b0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a4c0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a4d0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a4e0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a4f0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a500: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
a510: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
a520: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
a530: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
a540: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a550: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a560: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a570: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a580: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
a590: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
a5a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a5b0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
a5c0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a5d0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a5e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
a5f0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
a600: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
a610: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
a620: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
a630: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
a640: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
a650: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
a660: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
a670: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
a680: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
a690: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
a6a0: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
a6b0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
a6c0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
a6d0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
a6e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a6f0: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
a700: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a710: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
a720: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
a730: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
a740: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
a750: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
a760: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
a770: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
a780: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
a790: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
a7a0: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
a7b0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a7c0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
a7d0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
a7e0: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
a7f0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
a800: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
a810: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
a820: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
a830: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a840: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
a850: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
a860: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
a870: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
a880: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
a890: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
a8a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
a8b0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
a8c0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
a8d0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
a8e0: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
a8f0: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
a900: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
a910: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a920: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
a930: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
a940: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
a950: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
a960: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
a970: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
a980: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
a990: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
a9a0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a9b0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
a9c0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
a9d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a9e0: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
a9f0: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
aa00: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
aa10: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
aa20: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
aa30: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
aa40: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
aa50: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
aa60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
aa70: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
aa80: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
aa90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
aaa0: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
aab0: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
aac0: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
aad0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
aae0: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
aaf0: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
ab00: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
ab10: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
ab20: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
ab30: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
ab40: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
ab50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ab60: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
ab70: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
ab80: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
ab90: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
aba0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
abb0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
abc0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
abd0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
abe0: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
abf0: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
ac00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
ac10: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
ac20: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
ac30: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
ac40: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
ac50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ac60: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ac70: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
ac80: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
ac90: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
aca0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
acb0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
acc0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
acd0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
ace0: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
acf0: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
ad00: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
ad10: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
ad20: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
ad30: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
ad40: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
ad50: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
ad60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ad70: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
ad80: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
ad90: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
ada0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
adb0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
adc0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
add0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
ade0: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
adf0: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
ae00: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
ae10: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
ae20: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
ae30: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
ae40: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
ae50: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
ae60: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
ae70: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
ae80: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
ae90: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
aea0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
aeb0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
aec0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
aed0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
aee0: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
aef0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
af00: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
af10: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
af20: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
af30: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
af40: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
af50: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
af60: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
af70: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
af80: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
af90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
afa0: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
afb0: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
afc0: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
afd0: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
afe0: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
aff0: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
b000: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
b010: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b020: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b030: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
b040: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
b050: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b060: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
b070: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
b080: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
b090: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
b0a0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
b0b0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
b0c0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
b0d0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
b0e0: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
b0f0: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
b100: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
b110: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b120: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b130: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
b140: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
b150: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
b160: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
b170: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
b180: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
b190: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b1a0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b1b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b1c0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b1d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b1e0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
b1f0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
b200: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
b210: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
b220: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
b230: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
b240: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
b250: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
b260: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
b270: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
b280: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
b290: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
b2a0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
b2b0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
b2c0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
b2d0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
b2e0: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
b2f0: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
b300: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
b310: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
b320: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
b330: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
b340: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
b350: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
b360: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
b370: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
b380: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
b390: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
b3a0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
b3b0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
b3c0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
b3d0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
b3e0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
b3f0: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
b400: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
b410: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
b420: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
b430: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
b440: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
b450: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
b460: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b480: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
b490: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
b4a0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
b4b0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b4c0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
b4d0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
b4e0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
b4f0: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b500: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
b510: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
b520: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
b530: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
b540: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b550: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
b560: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
b570: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
b580: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b590: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
b5a0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
b5b0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
b5c0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
b5d0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
b5e0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b5f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
b600: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
b610: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
b620: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
b630: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
b640: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
b650: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
b660: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b670: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b680: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b690: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
b6a0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
b6b0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
b6c0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
b6d0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
b6e0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b6f0: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b700: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b710: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b720: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b730: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b740: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b750: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b760: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b770: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b780: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b790: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b7a0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b7b0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b7c0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b7d0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b7e0: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b7f0: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b800: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b810: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b820: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b830: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b840: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b850: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b860: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b870: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b880: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b890: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b8a0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b8b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b8c0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b8d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b8e0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
b8f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
b900: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
b910: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
b920: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
b930: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
b940: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
b950: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
b960: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
b970: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b980: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
b990: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
b9a0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
b9b0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
b9c0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
b9d0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
b9e0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
b9f0: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
ba00: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
ba10: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
ba20: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
ba30: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
ba40: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
ba50: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
ba60: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
ba70: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ba80: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
ba90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
baa0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
bab0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
bac0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
bad0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
bae0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
baf0: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
bb00: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
bb10: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
bb20: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
bb30: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
bb40: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
bb50: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
bb60: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
bb70: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
bb80: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bb90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bba0: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_GET_HANDLE]].
bbb0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bbc0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
bbd0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61  ANDLE] opcode ca
bbe0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
bbf0: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72  ain the.** under
bc00: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c  lying native fil
bc10: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61  e handle associa
bc20: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20  ted with a file 
bc30: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69  handle.  This fi
bc40: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e  le.** control in
bc50: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
bc60: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74  ument as a point
bc70: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66  er to a native f
bc80: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a  ile handle and.*
bc90: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73  * writes the res
bca0: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65  ulting value the
bcb0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  re..**.** <li>[[
bcc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bcd0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
bce0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bcf0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
bd00: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
bd10: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
bd20: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
bd30: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
bd40: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
bd50: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
bd60: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
bd70: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
bd80: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
bd90: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
bda0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
bdb0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
bdc0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
bdd0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
bde0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
bdf0: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
be00: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
be10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
be20: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
be30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
be40: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
be50: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
be60: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
be70: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
be80: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
be90: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
bea0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
beb0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
bec0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
bed0: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
bee0: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
bef0: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
bf00: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
bf10: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
bf20: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
bf30: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
bf40: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
bf50: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
bf60: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
bf70: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
bf80: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
bf90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
bfa0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
bfb0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
bfc0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
bfd0: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
bfe0: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
bff0: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
c000: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c010: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
c020: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
c030: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c040: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
c050: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c060: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
c070: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
c080: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
c090: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
c0a0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
c0b0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
c0c0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
c0d0: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
c0e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
c0f0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
c100: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c110: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
c120: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
c130: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c140: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c150: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
c160: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c170: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c180: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
c190: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
c1a0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
c1b0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
c1c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
c1d0: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
c1e0: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
c1f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
c200: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
c210: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
c220: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
c230: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
c240: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
c250: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
c260: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
c270: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
c280: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
c290: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
c2a0: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
c2b0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
c2c0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
c2d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c2e0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
c2f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
c300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c310: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
c320: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
c330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c340: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
c350: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
c360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c370: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
c380: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
c390: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c3a0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
c3b0: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
c3c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c3d0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
c3e0: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
c3f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c400: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
c410: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
c420: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c430: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
c440: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
c450: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
c460: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
c470: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
c480: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
c490: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
c4a0: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
c4b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c4c0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
c4d0: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
c4e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c4f0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
c500: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
c510: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c520: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
c530: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
c540: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c550: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c560: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
c570: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
c580: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c590: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
c5a0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
c5b0: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
c5c0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
c5d0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
c5e0: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
c5f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c600: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
c610: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a  HANDLE       29.
c620: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c630: 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20  CNTL_PDB        
c640: 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 0a              30..
c650: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61  /* deprecated na
c660: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mes */.#define S
c670: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
c680: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
c690: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
c6a0: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
c6b0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
c6c0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
c6d0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53    SQLITE_FCNTL_S
c6e0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c6f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c700: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
c710: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43         SQLITE_FC
c720: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a  NTL_LAST_ERRNO..
c730: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c740: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
c750: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
c760: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
c770: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
c780: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
c790: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
c7a0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
c7b0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
c7c0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
c7d0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
c7e0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
c7f0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
c800: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
c810: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
c820: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
c830: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
c840: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
c850: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
c860: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
c870: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
c880: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
c890: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
c8a0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
c8b0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
c8c0: 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20  I3REF: Loadable 
c8d0: 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a  Extension Thunk.
c8e0: 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
c8f0: 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71  to the opaque sq
c900: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
c910: 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  es structure is 
c920: 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
c930: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
c940: 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73   to entry points
c950: 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78   of [loadable ex
c960: 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73  tensions].  This
c970: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75  .** structure mu
c980: 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20  st be typedefed 
c990: 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b  in order to work
c9a0: 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72   around compiler
c9b0: 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20   warnings.** on 
c9c0: 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a  some platforms..
c9d0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c9e0: 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  t sqlite3_api_ro
c9f0: 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61  utines sqlite3_a
ca00: 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a  pi_routines;../*
ca10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
ca20: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
ca30: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
ca40: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
ca50: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
ca60: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
ca70: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
ca80: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
ca90: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
caa0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
cab0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
cac0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
cad0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
cae0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
caf0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
cb00: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
cb10: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
cb20: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
cb30: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
cb40: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
cb50: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
cb60: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
cb70: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
cb80: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
cb90: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
cba0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
cbb0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
cbc0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
cbd0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
cbe0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
cbf0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
cc00: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
cc10: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
cc20: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
cc30: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
cc40: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
cc50: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
cc60: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
cc70: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
cc80: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
cc90: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
cca0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
ccb0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
ccc0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
ccd0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
cce0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
ccf0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
cd00: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
cd10: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
cd20: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
cd30: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
cd40: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
cd50: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
cd60: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
cd70: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
cd80: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
cd90: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
cda0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
cdb0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
cdc0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
cdd0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
cde0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
cdf0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
ce00: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
ce10: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
ce20: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
ce30: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
ce40: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
ce50: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
ce60: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
ce70: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
ce80: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
ce90: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
cea0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
ceb0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
cec0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
ced0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
cee0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
cef0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
cf00: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
cf10: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
cf20: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
cf30: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
cf40: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
cf50: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
cf60: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
cf70: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
cf80: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
cf90: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
cfa0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
cfb0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
cfc0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
cfd0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
cfe0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
cff0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
d000: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
d010: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
d020: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
d030: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
d040: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
d050: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
d060: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
d070: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
d080: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
d090: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
d0a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
d0b0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
d0c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
d0d0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
d0e0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
d0f0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
d100: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
d110: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
d120: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
d130: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
d140: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
d150: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
d160: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
d170: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
d180: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
d190: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
d1a0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
d1b0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
d1c0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
d1d0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
d1e0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
d1f0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
d200: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
d210: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
d220: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
d230: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
d240: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
d250: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
d260: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
d270: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
d280: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
d290: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
d2a0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
d2b0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
d2c0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
d2d0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d2e0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
d2f0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
d300: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
d310: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
d320: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
d330: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
d340: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
d350: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d360: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
d370: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
d380: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
d390: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
d3a0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
d3b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d3c0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
d3d0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
d3e0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
d3f0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
d400: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
d410: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
d420: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
d430: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
d440: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
d450: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
d460: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
d470: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
d480: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
d490: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
d4a0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
d4b0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
d4c0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
d4d0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
d4e0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
d4f0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
d500: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
d510: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
d520: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
d530: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
d540: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
d550: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
d560: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
d570: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
d580: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
d590: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
d5a0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
d5b0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
d5c0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
d5d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d5e0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
d5f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d600: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
d610: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d620: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
d630: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d640: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
d650: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d660: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
d670: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d680: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
d690: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d6a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
d6b0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
d6c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d6d0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
d6e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
d6f0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
d700: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
d710: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
d720: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
d730: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
d740: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
d750: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
d760: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
d770: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
d780: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
d790: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
d7a0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
d7b0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
d7c0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
d7d0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
d7e0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
d7f0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
d800: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
d810: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
d820: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
d830: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
d840: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
d850: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
d860: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
d870: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
d880: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
d890: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
d8a0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
d8b0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
d8c0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
d8d0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
d8e0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
d8f0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
d900: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
d910: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
d920: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
d930: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
d940: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
d950: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
d960: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
d970: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
d980: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
d990: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
d9a0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
d9b0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
d9c0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
d9d0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
d9e0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
d9f0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
da00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
da10: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
da20: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
da30: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
da40: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
da50: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
da60: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
da70: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
da80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
da90: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
daa0: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
dab0: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
dac0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
dad0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
dae0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
daf0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
db00: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
db10: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
db20: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
db30: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
db40: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
db50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
db60: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
db70: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
db80: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
db90: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
dba0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
dbb0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
dbc0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
dbd0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
dbe0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
dbf0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
dc00: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
dc10: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
dc20: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
dc30: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
dc40: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
dc50: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
dc60: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
dc70: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
dc80: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
dc90: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
dca0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
dcb0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
dcc0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
dcd0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
dce0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
dcf0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
dd00: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
dd10: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
dd20: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
dd30: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
dd40: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
dd50: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
dd60: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
dd70: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
dd80: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
dd90: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
dda0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
ddb0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
ddc0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
ddd0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
dde0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
ddf0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
de00: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
de10: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
de20: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
de30: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
de40: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
de50: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
de60: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
de70: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
de80: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
de90: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
dea0: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
deb0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
dec0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
ded0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
dee0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
def0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
df00: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
df10: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
df20: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
df30: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
df40: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
df50: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
df60: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
df70: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
df80: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
df90: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
dfa0: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
dfb0: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
dfc0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
dfd0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
dfe0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
dff0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
e000: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
e010: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
e020: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
e030: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
e040: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
e050: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
e060: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
e070: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
e080: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
e090: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
e0a0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
e0b0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
e0c0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
e0d0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
e0e0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
e0f0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
e100: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
e110: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
e120: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
e130: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
e140: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
e150: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
e160: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
e170: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
e180: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
e190: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
e1a0: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
e1b0: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
e1c0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
e1d0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
e1e0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
e1f0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
e200: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
e210: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
e220: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
e230: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
e240: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
e250: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
e260: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
e270: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
e280: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
e290: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
e2a0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
e2b0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
e2c0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
e2d0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
e2e0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
e2f0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
e300: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
e310: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
e320: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
e330: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
e340: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
e350: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
e360: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
e370: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
e380: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
e390: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
e3a0: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
e3b0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
e3c0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
e3d0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
e3e0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
e3f0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
e400: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
e410: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
e420: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
e430: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
e440: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
e450: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
e460: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
e470: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
e480: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
e490: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
e4a0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
e4b0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
e4c0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
e4d0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
e4e0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
e4f0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
e500: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
e510: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
e520: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
e530: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
e540: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
e550: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
e560: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
e570: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
e580: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
e590: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
e5a0: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
e5b0: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
e5c0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
e5d0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
e5e0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
e5f0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
e600: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
e610: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
e620: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
e630: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
e640: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
e650: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
e660: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
e670: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
e680: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
e690: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
e6a0: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
e6b0: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
e6c0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
e6d0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
e6e0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
e6f0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
e700: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
e710: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
e720: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
e730: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
e740: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
e750: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
e760: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
e770: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
e780: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
e790: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
e7a0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
e7b0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
e7c0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
e7d0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
e7e0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
e7f0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
e800: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
e810: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
e820: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
e830: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
e840: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
e850: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
e860: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
e870: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
e880: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
e890: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
e8a0: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
e8b0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
e8c0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
e8d0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
e8e0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
e8f0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
e900: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
e910: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
e920: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
e930: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
e940: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
e950: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
e960: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
e970: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
e980: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
e990: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
e9a0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
e9b0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
e9c0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
e9d0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
e9e0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
e9f0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
ea00: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
ea10: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
ea20: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
ea30: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
ea40: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
ea50: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
ea60: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
ea70: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
ea80: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
ea90: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
eaa0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
eab0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
eac0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ead0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
eae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
eaf0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
eb00: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
eb10: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
eb20: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
eb30: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
eb40: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
eb50: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
eb60: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
eb70: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
eb80: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
eb90: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
eba0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
ebb0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ebc0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
ebd0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
ebe0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
ebf0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
ec00: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ec10: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
ec20: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
ec30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ec40: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
ec50: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
ec60: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
ec70: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
ec80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
ec90: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
eca0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
ecb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
ecc0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
ecd0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
ece0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
ecf0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
ed00: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
ed10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ed20: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
ed30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
ed40: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
ed50: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
ed60: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
ed70: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
ed80: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
ed90: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
eda0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
edb0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
edc0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
edd0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
ede0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
edf0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
ee00: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
ee10: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
ee20: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
ee30: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
ee40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
ee50: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
ee60: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
ee70: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
ee80: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
ee90: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
eea0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
eeb0: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
eec0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
eed0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
eee0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
eef0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ef00: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ef10: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
ef20: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
ef30: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
ef40: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
ef50: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
ef60: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ef70: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
ef80: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
ef90: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
efa0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
efb0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
efc0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
efd0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
efe0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
eff0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
f000: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
f010: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
f020: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
f030: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
f040: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
f050: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
f060: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
f070: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
f080: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
f090: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
f0a0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
f0b0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
f0c0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
f0d0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
f0e0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
f0f0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
f100: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
f110: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
f120: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
f130: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
f140: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
f150: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
f160: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f170: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
f180: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f190: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
f1a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f1b0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
f1c0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
f1d0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
f1e0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
f1f0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
f200: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
f210: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
f220: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
f230: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
f240: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
f250: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
f260: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
f270: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
f280: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
f290: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
f2a0: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
f2b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
f2c0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
f2d0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
f2e0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
f2f0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
f300: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
f310: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
f320: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
f330: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
f340: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
f350: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f360: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
f370: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
f380: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
f390: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
f3a0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
f3b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
f3c0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
f3d0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
f3e0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
f3f0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
f400: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
f410: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
f420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
f430: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
f440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
f450: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
f460: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
f470: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
f480: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
f490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
f4a0: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
f4b0: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
f4c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f4d0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
f4e0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
f4f0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
f500: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
f510: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
f520: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
f530: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
f540: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
f550: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
f560: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
f570: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
f580: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
f590: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
f5a0: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
f5b0: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
f5c0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
f5d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
f5e0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
f5f0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
f600: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f610: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
f620: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f630: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f640: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
f650: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f660: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f670: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f680: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
f690: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
f6a0: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
f6b0: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
f6c0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
f6d0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
f6e0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
f6f0: 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
f700: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
f710: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
f720: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
f730: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
f740: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
f750: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
f760: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
f770: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
f780: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
f790: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
f7a0: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
f7b0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f7c0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
f7d0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
f7e0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
f7f0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
f800: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
f810: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
f820: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
f830: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
f840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
f850: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
f860: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
f870: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
f880: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
f890: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
f8a0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
f8b0: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
f8c0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
f8d0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
f8e0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
f8f0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
f900: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
f910: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
f920: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
f930: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
f940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f950: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
f960: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
f970: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
f980: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
f990: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
f9a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f9b0: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
f9c0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
f9d0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
f9e0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f9f0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
fa00: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
fa10: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
fa20: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
fa30: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
fa40: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
fa50: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
fa60: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
fa70: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
fa80: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
fa90: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
faa0: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
fab0: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
fac0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
fad0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
fae0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
faf0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
fb00: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
fb10: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
fb20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fb30: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
fb40: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
fb50: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
fb60: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
fb70: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
fb80: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
fb90: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
fba0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
fbb0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
fbc0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
fbd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
fbe0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
fbf0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
fc00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fc10: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
fc20: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
fc30: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
fc40: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
fc50: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
fc60: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
fc70: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
fc80: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
fc90: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
fca0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fcb0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
fcc0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
fcd0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
fce0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fcf0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
fd00: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
fd10: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
fd20: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
fd30: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
fd40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fd50: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
fd60: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
fd70: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
fd80: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
fd90: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
fda0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
fdb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fdc0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fdd0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
fde0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
fdf0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
fe00: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
fe10: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fe20: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
fe30: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
fe40: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
fe50: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
fe60: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
fe70: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
fe80: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
fe90: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
fea0: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
feb0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
fec0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
fed0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
fee0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
fef0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
ff00: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
ff10: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
ff20: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
ff30: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
ff40: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
ff50: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
ff60: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
ff70: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
ff80: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
ff90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
ffa0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
ffb0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
ffc0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
ffd0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
ffe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fff0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
10000 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
10010 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
10020 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
10030 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
10040 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
10050 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
10060 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
10070 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
10080 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
10090 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
100a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
100b0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
100c0 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
100d0 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
100e0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
100f0 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
10100 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
10110 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
10120 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
10130 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10140 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
10150 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
10160 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
10170 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
10180 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
10190 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
101a0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
101b0 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
101c0 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
101d0 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
101e0 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
101f0 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
10200 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
10210 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
10220 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10230 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
10240 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
10250 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10260 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
10270 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
10280 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
10290 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
102a0 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
102b0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
102c0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
102d0 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
102e0 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
102f0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
10300 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
10310 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
10320 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
10330 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
10340 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
10350 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
10360 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10370 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
10380 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
10390 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
103a0 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
103b0 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
103c0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
103d0 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
103e0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
103f0 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
10400 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
10410 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10420 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
10430 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
10440 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
10450 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
10460 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
10470 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
10480 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10490 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
104a0 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
104b0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
104c0 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
104d0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
104e0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
104f0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
10500 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
10510 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
10520 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
10530 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
10540 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
10550 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
10560 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
10570 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
10580 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
10590 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
105a0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
105b0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
105c0 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
105d0 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
105e0 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
105f0 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
10600 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
10610 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
10620 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10630 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
10640 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
10650 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
10660 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
10670 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
10680 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
10690 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
106a0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
106b0 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
106c0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
106d0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
106e0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
106f0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10700 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
10710 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
10720 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
10730 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10740 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
10750 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
10760 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
10770 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
10780 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
10790 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
107a0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
107b0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
107c0 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
107d0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
107e0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
107f0 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
10800 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
10810 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
10820 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
10830 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
10840 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
10850 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
10860 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
10870 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
10880 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
10890 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
108a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
108b0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
108c0 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
108d0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
108e0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
108f0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
10900 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
10910 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10920 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
10930 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
10940 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
10950 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
10960 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
10970 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
10980 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
10990 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
109a0 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
109b0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
109c0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
109d0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
109e0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
109f0 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
10a00 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10a10 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
10a20 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
10a30 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
10a40 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10a50 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
10a60 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
10a70 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
10a80 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
10a90 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
10aa0 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
10ab0 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
10ac0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
10ad0 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
10ae0 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
10af0 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
10b00 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
10b10 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
10b20 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
10b30 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
10b40 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
10b50 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
10b60 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
10b70 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
10b80 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73  ..**.** <b>The s
10b90 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10ba0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
10bb0 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65   threadsafe. The
10bc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
10bd0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
10be0 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
10bf0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
10c00 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
10c10 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
10c20 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10c30 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f  () is running.</
10c40 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  b>.**.** The sql
10c50 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10c60 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f  terface.** may o
10c70 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
10c80 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
10c90 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
10ca0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
10cb0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
10cc0 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
10cd0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
10ce0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
10cf0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10d00 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
10d10 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
10d20 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
10d30 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
10d40 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
10d50 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
10d60 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
10d70 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
10d80 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
10d90 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
10da0 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
10db0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
10dc0 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
10dd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
10de0 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
10df0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
10e00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
10e10 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
10e20 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
10e30 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
10e40 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
10e50 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
10e60 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
10e70 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
10e80 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
10e90 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
10ea0 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
10eb0 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
10ec0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
10ed0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
10ee0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
10ef0 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
10f00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
10f10 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
10f20 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
10f30 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
10f40 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
10f50 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
10f60 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
10f70 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
10f80 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
10f90 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
10fa0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
10fb0 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
10fc0 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
10fd0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
10fe0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
10ff0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11000 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
11010 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
11020 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
11030 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
11040 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
11050 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
11060 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
11070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11080 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
11090 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
110a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
110b0 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
110c0 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
110d0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
110e0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
110f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
11100 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
11110 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
11120 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
11130 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
11140 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
11150 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
11160 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
11170 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
11180 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
11190 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
111a0 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
111b0 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
111c0 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
111d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
111e0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
111f0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
11200 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
11210 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
11220 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
11230 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
11240 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
11250 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
11260 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
11270 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
11280 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
11290 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
112a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
112b0 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
112c0 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
112d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
112e0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
112f0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
11300 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
11310 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
11320 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
11330 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
11340 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
11350 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
11360 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
11370 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
11380 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
11390 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
113a0 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
113b0 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
113c0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
113d0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
113e0 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
113f0 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
11400 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
11410 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
11420 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
11430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11440 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
11450 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
11460 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
11470 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
11480 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
11490 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
114a0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
114b0 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
114c0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
114d0 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
114e0 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
114f0 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
11500 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
11510 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
11520 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
11530 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
11540 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
11550 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
11560 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
11570 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
11580 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
11590 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
115a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
115b0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
115c0 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
115d0 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
115e0 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
115f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
11600 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
11610 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
11620 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
11630 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
11640 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
11650 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
11660 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
11670 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
11680 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
11690 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
116a0 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
116b0 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
116c0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
116d0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
116e0 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
116f0 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
11700 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
11710 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
11720 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
11730 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
11740 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
11750 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
11760 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
11770 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
11780 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
11790 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
117a0 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
117b0 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
117c0 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
117d0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
117e0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
117f0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
11800 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
11810 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
11820 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
11830 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
11840 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
11850 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
11860 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
11870 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
11880 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
11890 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
118a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
118b0 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
118c0 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
118d0 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
118e0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
118f0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
11900 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
11910 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
11920 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
11930 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
11940 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
11950 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
11960 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
11970 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
11980 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
11990 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
119a0 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
119b0 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
119c0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
119d0 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
119e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
119f0 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
11a00 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
11a10 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
11a20 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
11a30 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
11a40 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
11a50 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
11a60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11a70 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
11a80 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
11a90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
11aa0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
11ab0 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
11ac0 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
11ad0 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
11ae0 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
11af0 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
11b00 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
11b10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
11b20 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
11b30 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
11b40 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
11b50 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
11b60 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
11b70 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
11b80 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
11b90 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
11ba0 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
11bb0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
11bc0 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
11bd0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
11be0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
11bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
11c00 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
11c10 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
11c20 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
11c30 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
11c40 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
11c50 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
11c60 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
11c70 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
11c80 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
11c90 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
11ca0 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
11cb0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
11cc0 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
11cd0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
11ce0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
11cf0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
11d00 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
11d10 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
11d20 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
11d30 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
11d40 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
11d50 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
11d60 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
11d70 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
11d80 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
11d90 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
11da0 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
11db0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
11dc0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
11dd0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
11de0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
11df0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11e00 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
11e10 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
11e20 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
11e30 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
11e40 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
11e50 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
11e60 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
11e70 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
11e80 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
11e90 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
11ea0 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
11eb0 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
11ec0 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
11ed0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
11ee0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
11ef0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
11f00 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
11f10 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
11f20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
11f30 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
11f40 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
11f50 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
11f60 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
11f70 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
11f80 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
11f90 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
11fa0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11fb0 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
11fc0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
11fd0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
11fe0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
11ff0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
12000 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
12010 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
12020 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
12030 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
12040 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
12050 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
12060 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
12070 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
12080 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
12090 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
120a0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
120b0 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
120c0 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
120d0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
120e0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
120f0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
12100 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
12110 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
12120 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
12130 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
12140 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
12150 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
12160 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
12170 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
12180 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
12190 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
121a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
121b0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
121c0 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
121d0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
121e0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
121f0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
12200 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
12210 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
12220 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
12230 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
12240 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
12250 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
12260 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
12270 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
12280 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12290 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
122a0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
122b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
122c0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
122d0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
122e0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
122f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12300 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
12310 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
12320 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
12330 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
12340 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12350 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
12360 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
12370 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
12380 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
12390 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
123a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
123b0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
123c0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
123d0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
123e0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
123f0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
12400 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
12410 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
12420 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
12430 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
12440 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12450 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
12460 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
12470 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12480 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
12490 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
124a0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
124b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
124c0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
124d0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
124e0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
124f0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12500 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12510 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
12520 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
12530 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
12540 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
12550 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
12560 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
12570 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
12580 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
12590 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
125a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
125b0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
125c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
125d0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
125e0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
125f0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12600 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12610 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
12620 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
12630 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
12640 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
12650 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
12660 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
12670 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
12680 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
12690 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
126a0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
126b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
126c0 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
126d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
126e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
126f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12700 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
12710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12720 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
12730 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12740 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12750 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12760 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12770 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12780 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
12790 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
127a0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
127b0 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
127c0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
127d0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
127e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
127f0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
12800 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
12810 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
12820 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
12830 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
12840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
12850 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12860 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
12870 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
12880 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
12890 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
128a0 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
128b0 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
128c0 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
128d0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
128e0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
128f0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
12900 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
12910 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
12920 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
12930 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
12940 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12950 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
12960 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
12970 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
12980 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
12990 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
129a0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
129b0 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
129c0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
129d0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
129e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
129f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12a00 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12a10 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12a20 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12a30 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
12a40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12a50 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12a70 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
12a80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12a90 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
12aa0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
12ab0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12ac0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
12ad0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12ae0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
12af0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
12b00 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
12b10 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
12b20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
12b30 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
12b40 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
12b50 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
12b60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12b70 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
12b80 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
12b90 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
12ba0 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
12bb0 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
12bc0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12bd0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
12be0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
12bf0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
12c00 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
12c10 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
12c20 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
12c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
12c40 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
12c50 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
12c60 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
12c70 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
12c80 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
12c90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12ca0 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
12cb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12cc0 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
12cd0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
12ce0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
12cf0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
12d00 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
12d10 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
12d20 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
12d30 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
12d40 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12d50 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12d60 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
12d70 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
12d80 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
12d90 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
12da0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
12db0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
12dc0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
12dd0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
12de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12df0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
12e00 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
12e10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12e20 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
12e30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12e40 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
12e50 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
12e60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12e70 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
12e80 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12e90 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
12ea0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12eb0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12ec0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12ed0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12ee0 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
12ef0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
12f00 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
12f10 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
12f20 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
12f30 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
12f40 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
12f50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12f60 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
12f70 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
12f80 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
12f90 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
12fa0 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
12fb0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12fc0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12fd0 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
12fe0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
12ff0 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
13000 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
13010 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13020 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
13030 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
13040 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
13050 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
13060 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13070 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
13080 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13090 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
130a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
130b0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
130c0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
130d0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
130e0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
130f0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
13100 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
13110 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
13120 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
13130 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13140 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
13150 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
13160 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
13170 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
13180 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13190 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
131a0 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
131b0 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
131c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
131d0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
131e0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
131f0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
13200 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13210 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
13220 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
13230 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
13240 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
13250 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
13260 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
13270 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
13280 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
13290 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
132a0 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
132b0 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
132c0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
132d0 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
132e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
132f0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
13300 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
13310 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
13320 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
13330 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
13340 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
13350 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
13360 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
13370 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
13380 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
13390 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
133a0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
133b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
133c0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
133d0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
133e0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
133f0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
13400 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tus64()].**   </
13410 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
13420 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
13430 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
13440 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
13450 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
13460 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
13470 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
13480 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
13490 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
134a0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
134b0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
134c0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
134d0 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
134e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
134f0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
13500 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
13510 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
13520 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13530 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
13540 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
13550 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
13560 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53  buffer.** that S
13570 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
13580 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  r scratch memory
13590 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74  .  ^(There are t
135a0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a  hree arguments.*
135b0 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  * to SQLITE_CONF
135c0 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70  IG_SCRATCH:  A p
135d0 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
135e0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
135f0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
13600 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
13610 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
13620 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
13630 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
13640 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
13650 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
13660 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
13670 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
13680 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e  locations (N).)^
13690 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
136a0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
136b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
136c0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
136d0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
136e0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
136f0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
13700 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73  Lite will not us
13710 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  e more than one 
13720 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
13730 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e  per thread..** ^
13740 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
13750 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61  r request a scra
13760 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
13770 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
13780 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
13790 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a  base page size..
137a0 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  ** ^If SQLite ne
137b0 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
137c0 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
137d0 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
137e0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
137f0 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
13800 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
13810 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
13820 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
13830 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
13840 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
13850 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74  d.<p>.** ^When t
13860 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70  he application p
13870 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75  rovides any amou
13880 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65  nt of scratch me
13890 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51  mory using.** SQ
138a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
138b0 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69  TCH, SQLite avoi
138c0 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c  ds unnecessary l
138d0 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  arge.** [sqlite3
138e0 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c  _malloc|heap all
138f0 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  ocations]..** Th
13900 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62  is can help [Rob
13910 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e  son proof|preven
13920 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
13930 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75  ion failures] du
13940 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61  e to heap.** fra
13950 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f  gmentation in lo
13960 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65  w-memory embedde
13970 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f  d systems..** </
13980 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13990 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
139a0 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
139b0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
139c0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
139d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
139e0 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69  G_PAGECACHE opti
139f0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d  on specifies a m
13a00 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68  emory pool.** th
13a10 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
13a20 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  e for the databa
13a30 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
13a40 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
13a50 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
13a60 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
13a70 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
13a80 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61  tion option is a
13a90 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70   no-op if an app
13aa0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
13ab0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
13ac0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
13ad0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
13ae0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13af0 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68  PCACHE2]..** ^Th
13b00 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13b10 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13b20 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13b30 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
13b40 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
13b50 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29  ed memory (pMem)
13b60 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
13b70 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69  ch page cache li
13b80 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  ne (sz),.** and 
13b90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61  the number of ca
13ba0 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a  che lines (N)..*
13bb0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
13bc0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
13bd0 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
13be0 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
13bf0 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
13c00 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
13c10 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73   and 65536) plus
13c20 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65   some extra byte
13c30 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  s for each.** pa
13c40 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
13c50 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
13c60 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79   bytes needed by
13c70 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72   the page header
13c80 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
13c90 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c  mined using [SQL
13ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13cb0 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74  E_HDRSZ]..** ^It
13cc0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
13cd0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
13ce0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
13cf0 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
13d00 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
13d10 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
13d20 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72    The pMem.** ar
13d30 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65  gument must be e
13d40 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
13d50 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65  nter or a pointe
13d60 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  r to an 8-byte.*
13d70 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  * aligned block 
13d80 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  of memory of at 
13d90 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
13da0 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73  , otherwise.** s
13db0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
13dc0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
13dd0 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69  .** ^When pMem i
13de0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
13df0 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74  te will strive t
13e00 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  o use the memory
13e10 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20   provided.** to 
13e20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63  satisfy page cac
13e30 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e  he needs, fallin
13e40 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74  g back to [sqlit
13e50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a  e3_malloc()] if.
13e60 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20  ** a page cache 
13e70 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74  line is larger t
13e80 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20  han sz bytes or 
13e90 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d  if all of the pM
13ea0 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  em buffer.** is 
13eb0 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49  exhausted..** ^I
13ec0 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61  f pMem is NULL a
13ed0 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  nd N is non-zero
13ee0 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61  , then each data
13ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
13f00 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69  ** does an initi
13f10 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69  al bulk allocati
13f20 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  on for page cach
13f30 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d  e memory.** from
13f40 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13f50 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66  ()] sufficient f
13f60 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73  or N cache lines
13f70 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
13f80 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34  e or.** of -1024
13f90 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73  *N bytes if N is
13fa0 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66   negative, . ^If
13fb0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
13fc0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
13fd0 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
13fe0 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
13ff0 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61  ed by the initia
14000 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  l.** allocation,
14010 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65   then SQLite goe
14020 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
14030 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65  lloc()] separate
14040 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61  ly for each.** a
14050 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20  dditional cache 
14060 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  line. </dd>.**.*
14070 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14080 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
14090 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
140a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
140b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
140c0 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63  HEAP option spec
140d0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
140e0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a  emory buffer .**
140f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
14100 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  l use for all of
14110 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
14120 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
14130 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74  eeds.** beyond t
14140 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f  hose provided fo
14150 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
14160 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
14170 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
14180 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
14190 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
141a0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
141b0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
141c0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
141d0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
141e0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
141f0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
14200 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
14210 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
14220 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
14230 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
14240 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
14250 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
14260 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
14270 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14280 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
14290 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
142a0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
142b0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
142c0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
142d0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
142e0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
142f0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
14300 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
14310 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
14320 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
14330 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
14340 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
14350 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
14360 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14370 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
14380 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
14390 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
143a0 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
143b0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
143c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
143d0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
143e0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
143f0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
14400 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
14410 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
14420 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
14430 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
14440 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
14450 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
14460 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
14470 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
14480 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
14490 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
144a0 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
144b0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
144c0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
144d0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
144e0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
144f0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14500 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
14510 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
14520 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
14530 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
14540 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
14550 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
14560 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
14570 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14580 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
14590 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
145a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
145b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
145c0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
145d0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
145e0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
145f0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
14600 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
14610 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14620 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14630 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
14640 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
14650 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
14660 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
14670 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
14680 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
14690 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
146a0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
146b0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
146c0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
146d0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
146e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
146f0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14700 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
14710 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
14720 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
14730 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
14740 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14750 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14760 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14770 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14780 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14790 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
147a0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
147b0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
147c0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
147d0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
147e0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
147f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14800 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14810 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
14820 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14830 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
14840 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14850 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14870 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
14880 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
14890 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
148a0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
148b0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
148c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
148d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
148e0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
148f0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14900 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14910 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14920 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
14930 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
14940 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
14950 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
14960 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
14970 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
14980 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
14990 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
149a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
149b0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
149c0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
149d0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
149e0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
149f0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
14a00 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
14a10 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
14a20 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
14a30 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
14a40 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
14a50 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
14a60 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
14a70 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14a80 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14a90 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14aa0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
14ab0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
14ac0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
14ad0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
14ae0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
14af0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14b00 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
14b10 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14b20 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
14b30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
14b40 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
14b50 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
14b60 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14b70 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14b80 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
14b90 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14ba0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14bb0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14bc0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
14bd0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
14be0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
14bf0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
14c00 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
14c10 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
14c20 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
14c30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
14c40 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14c50 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
14c60 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
14c70 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
14c80 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
14c90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
14ca0 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
14cb0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
14cc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
14cd0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
14ce0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
14cf0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
14d00 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
14d10 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
14d20 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
14d30 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
14d40 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
14d50 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
14d60 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
14d70 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
14d80 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
14d90 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
14da0 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
14db0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14dc0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14dd0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14de0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
14df0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14e10 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14e20 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14e30 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
14e40 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
14e50 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
14e60 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14e70 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
14e80 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
14e90 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
14ea0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
14eb0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14ec0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
14ed0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
14ee0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
14ef0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
14f00 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
14f10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14f20 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
14f30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14f40 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
14f50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14f70 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14f80 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14f90 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
14fa0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14fb0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
14fc0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14fd0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
14fe0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
14ff0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
15000 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
15010 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
15020 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
15030 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15040 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
15050 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
15060 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
15070 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
15080 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
15090 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
150a0 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
150b0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
150c0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
150d0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
150e0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
150f0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
15100 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
15110 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
15120 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
15130 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
15140 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
15150 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
15160 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
15170 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
15180 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
15190 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
151a0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
151b0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
151c0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
151d0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
151e0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
151f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
15200 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
15210 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
15220 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
15230 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
15240 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15250 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
15260 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
15270 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
15280 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15290 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
152a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
152b0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
152c0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
152d0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
152e0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
152f0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
15300 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
15310 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
15320 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15330 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
15340 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
15350 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
15360 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
15370 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
15380 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
15390 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
153a0 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
153b0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
153c0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
153d0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
153e0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
153f0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
15400 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
15410 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
15420 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
15430 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
15440 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
15450 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
15460 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
15470 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
15480 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
15490 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
154a0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
154b0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
154c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
154d0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
154e0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
154f0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
15500 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15510 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
15520 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15530 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
15540 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15550 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
15560 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15570 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
15580 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
15590 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
155a0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
155b0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
155c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
155d0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
155e0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
155f0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
15600 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
15610 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
15620 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
15630 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
15640 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
15650 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
15660 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
15670 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
15680 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
15690 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
156a0 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
156b0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
156c0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
156d0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
156e0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
156f0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
15700 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
15710 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
15720 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
15730 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
15740 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
15750 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
15760 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
15770 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
15780 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
15790 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
157a0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
157b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
157c0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
157d0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
157e0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
157f0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
15800 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
15810 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
15820 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
15830 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
15840 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
15850 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
15860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15870 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15880 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15890 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
158a0 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
158b0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
158c0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
158d0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
158e0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
158f0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
15900 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
15910 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
15920 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
15930 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
15940 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
15950 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
15960 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
15970 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
15980 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
15990 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
159a0 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
159b0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
159c0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
159d0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
159e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
159f0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
15a00 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
15a10 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
15a20 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
15a30 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
15a40 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
15a50 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15a60 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15a70 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
15a80 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
15a90 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
15aa0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
15ab0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
15ac0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
15ad0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
15ae0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
15af0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
15b00 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
15b10 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
15b20 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
15b30 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
15b40 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
15b50 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
15b60 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
15b70 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
15b80 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
15b90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
15ba0 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
15bb0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
15bc0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15bd0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
15be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15bf0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
15c00 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
15c10 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
15c20 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
15c30 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
15c40 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
15c50 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
15c60 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
15c70 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
15c80 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
15c90 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15ca0 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
15cb0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
15cc0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
15cd0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
15ce0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
15cf0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
15d00 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
15d10 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
15d20 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
15d30 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
15d40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15d50 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
15d60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
15d70 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
15d80 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
15d90 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
15da0 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
15db0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
15dc0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
15dd0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
15de0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
15df0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
15e00 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
15e10 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
15e20 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
15e30 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
15e40 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15e50 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
15e60 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15e70 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
15e80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15e90 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
15ea0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15eb0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
15ec0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
15ed0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
15ee0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
15ef0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
15f00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
15f10 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
15f20 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
15f30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15f40 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
15f50 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
15f60 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
15f70 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
15f80 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
15f90 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
15fa0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
15fb0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
15fc0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
15fd0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
15fe0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
15ff0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
16000 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
16010 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16020 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
16030 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
16040 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
16050 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
16060 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
16070 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
16080 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
16090 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
160a0 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
160b0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
160c0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
160d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
160e0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
160f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16100 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
16110 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
16120 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
16130 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
16140 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
16150 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
16160 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
16170 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
16180 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
16190 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
161a0 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
161b0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
161c0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
161d0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
161e0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
161f0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
16200 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
16210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16220 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
16230 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
16240 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
16250 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
16260 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
16270 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
16280 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
16290 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
162a0 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
162b0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
162c0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
162d0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
162e0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
162f0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
16300 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
16310 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
16320 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
16330 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
16340 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16350 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
16360 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
16370 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
16380 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
16390 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
163a0 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
163b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
163c0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
163d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
163e0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
163f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16400 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16410 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
16420 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
16430 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
16440 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
16450 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
16460 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
16470 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
16480 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
16490 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
164a0 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
164b0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
164c0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
164d0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
164e0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
164f0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
16500 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
16510 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
16520 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
16530 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ap..**.** [[SQLI
16540 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16550 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
16560 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16570 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
16580 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16590 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
165a0 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
165b0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
165c0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
165d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
165e0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
165f0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
16600 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
16610 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
16620 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
16630 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
16640 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
16650 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
16660 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65   The amount of e
16670 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
16680 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
16690 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
166a0 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
166b0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
166c0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
166d0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
166e0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a  _CONFIG_PMASZ]].
166f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16700 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64  NFIG_PMASZ.** <d
16710 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16720 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f  NFIG_PMASZ optio
16730 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
16740 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
16750 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  .** is an unsign
16760 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73  ed integer and s
16770 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d  ets the "Minimum
16780 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74   PMA Size" for t
16790 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  he multithreaded
167a0 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68  .** sorter to th
167b0 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  at integer.  The
167c0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d   default minimum
167d0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74   PMA Size is set
167e0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
167f0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d  TE_SORTER_PMASZ]
16800 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16810 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61  tion.  New threa
16820 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a  ds are launched.
16830 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20  ** to help with 
16840 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20  sort operations 
16850 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64  when multithread
16860 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73  ed sorting.** is
16870 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20   enabled (using 
16880 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65  the [PRAGMA thre
16890 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e  ads] command) an
168a0 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  d the amount of 
168b0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  content.** to be
168c0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20   sorted exceeds 
168d0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69  the page size ti
168e0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  mes the minimum 
168f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d  of the.** [PRAGM
16900 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65  A cache_size] se
16910 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76  tting and this v
16920 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  alue..**.** [[SQ
16930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16940 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20  JRNL_SPILL]].** 
16950 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16960 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
16970 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
16980 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
16990 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e  RNL_SPILL option
169a0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
169b0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
169c0 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b  ** becomes the [
169d0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
169e0 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b  l] spill-to-disk
169f0 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a   threshold.  .**
16a00 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [Statement jour
16a10 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69  nals] are held i
16a20 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74  n memory until t
16a30 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79  heir size (in by
16a40 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20  tes).** exceeds 
16a50 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20  this threshold, 
16a60 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74  at which point t
16a70 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20  hey are written 
16a80 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69  to disk..** Or i
16a90 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20  f the threshold 
16aa0 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74  is -1, statement
16ab0 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c   journals are al
16ac0 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63  ways held.** exc
16ad0 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f  lusively in memo
16ae0 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e  ry..** Since man
16af0 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  y statement jour
16b00 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d  nals never becom
16b10 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67  e large, setting
16b20 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68   the spill.** th
16b30 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c  reshold to a val
16b40 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42  ue such as 64KiB
16b50 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64   can greatly red
16b60 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  uce the amount o
16b70 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65  f.** I/O require
16b80 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61  d to support sta
16b90 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e  tement rollback.
16ba0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
16bb0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73  value for this s
16bc0 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f  etting is contro
16bd0 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  lled by the.** [
16be0 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f  SQLITE_STMTJRNL_
16bf0 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74  SPILL] compile-t
16c00 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
16c10 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
16c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
16c30 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
16c40 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
16c50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16c60 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
16c70 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16c80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16c90 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
16ca0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16cb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16cc0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
16cd0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
16ce0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16cf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d00 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
16d10 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
16d20 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
16d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16d40 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
16d50 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
16d60 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
16d70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16d80 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
16d90 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
16da0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
16db0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16dc0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
16dd0 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
16de0 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
16df0 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
16e00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16e10 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
16e20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
16e30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e40 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
16e50 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
16e60 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
16e70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16e80 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
16e90 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
16ea0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16eb0 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
16ec0 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
16ed0 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
16ee0 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
16ef0 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
16f00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16f10 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
16f20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
16f30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f40 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
16f50 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
16f60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16f70 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
16f80 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
16f90 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
16fa0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
16fb0 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
16fc0 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
16fd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16fe0 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
16ff0 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
17000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17010 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
17020 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
17030 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
17040 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
17050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
17060 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
17070 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
17080 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
17090 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
170a0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
170b0 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
170c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
170d0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
170e0 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
170f0 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
17100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17110 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
17120 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
17130 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
17140 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
17150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17160 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
17170 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
17180 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
17190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
171a0 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20  ACHE_HDRSZ      
171b0 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73    24  /* int *ps
171c0 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  z */.#define SQL
171d0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
171e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
171f0 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69  5  /* unsigned i
17200 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66  nt szPma */.#def
17210 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17220 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
17230 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e 74        26  /* int
17240 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   nByte */../*.**
17250 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
17260 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
17270 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
17280 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
17290 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
172a0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
172b0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
172c0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
172d0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
172e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
172f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
17300 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17310 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
17320 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
17330 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17340 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
17350 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
17360 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
17370 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
17380 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
17390 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
173a0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
173b0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
173c0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
173d0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
173e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
173f0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
17400 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
17410 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
17420 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
17430 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
17440 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
17450 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
17460 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
17470 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
17480 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17490 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
174a0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
174b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
174c0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
174d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
174e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
174f0 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
17500 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
17510 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
17520 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
17530 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
17540 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
17550 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
17560 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
17570 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
17580 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
17590 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
175a0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
175b0 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
175c0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
175d0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
175e0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
175f0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
17600 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
17610 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
17620 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
17630 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
17640 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
17650 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
17660 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
17670 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
17680 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
17690 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
176a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
176b0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
176c0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
176d0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
176e0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
176f0 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
17700 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
17710 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
17720 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
17730 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
17740 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
17750 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
17760 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
17770 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
17780 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
17790 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
177a0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
177b0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
177c0 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
177d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
177e0 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
177f0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
17800 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
17810 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
17820 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
17830 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
17840 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
17850 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
17860 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
17870 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
17880 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
17890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
178a0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
178b0 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
178c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
178d0 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
178e0 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
178f0 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
17900 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
17910 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
17920 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
17930 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
17940 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
17950 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
17960 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
17970 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
17980 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
17990 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
179a0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
179b0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
179c0 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
179d0 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
179e0 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
179f0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
17a00 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
17a10 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
17a20 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17a30 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
17a40 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17a50 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17a60 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17a70 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
17a80 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
17a90 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
17aa0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
17ab0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17ac0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17ad0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17ae0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17af0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17b00 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
17b10 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
17b20 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
17b30 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
17b40 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
17b50 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
17b60 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
17b70 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
17b80 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17b90 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17ba0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17bb0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17bc0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17bd0 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
17be0 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
17bf0 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
17c00 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
17c10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17c20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
17c30 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
17c40 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
17c50 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
17c60 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
17c70 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
17c80 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
17c90 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17ca0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
17cb0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17cc0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17cd0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
17ce0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
17cf0 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
17d00 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
17d10 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
17d20 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
17d30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
17d40 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
17d50 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
17d60 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
17d70 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
17d80 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
17d90 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
17da0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
17db0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
17dc0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17dd0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
17de0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
17df0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
17e00 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
17e10 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
17e20 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
17e30 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
17e40 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
17e50 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
17e60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
17e70 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
17e80 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
17e90 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
17ea0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
17eb0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17ec0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17ed0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17ee0 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
17ef0 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  NIZER</dt>.** <d
17f00 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
17f10 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
17f20 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
17f30 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a   two-argument.**
17f40 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
17f50 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28  [fts3_tokenizer(
17f60 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63  )] function whic
17f70 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  h is part of the
17f80 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d  .** [FTS3] full-
17f90 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69  text search engi
17fa0 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a  ne extension..**
17fb0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17fc0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17fd0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17fe0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17ff0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
18000 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
18010 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
18020 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69  zer() or.** posi
18030 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66  tive to enable f
18040 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
18050 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
18060 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
18070 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  .** unchanged..*
18080 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
18090 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
180a0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
180b0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
180c0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
180d0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
180e0 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e  ether fts3_token
180f0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
18100 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
18110 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
18120 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
18130 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
18140 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
18150 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
18160 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
18170 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
18180 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
18190 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
181a0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c  BCONFIG_ENABLE_L
181b0 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64  OAD_EXTENSION</d
181c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
181d0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
181e0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
181f0 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  able the [sqlite
18200 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
18210 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
18220 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f   independently o
18230 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  f the [load_exte
18240 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e  nsion()] SQL fun
18250 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73  ction..** The [s
18260 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
18270 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
18280 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  API enables or d
18290 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65  isables both the
182a0 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74  .** C-API [sqlit
182b0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
182c0 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c  n()] and the SQL
182d0 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f   function [load_
182e0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a  extension()]..**
182f0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
18300 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
18310 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68  arguments..** Wh
18320 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  en the first arg
18330 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e  ument to this in
18340 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74 68  terface is 1, th
18350 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50  en only the C-AP
18360 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20  I is.** enabled 
18370 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
18380 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73  tion remains dis
18390 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66  abled.  If the f
183a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
183b0 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61  .** this interfa
183c0 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f  ce is 0, then bo
183d0 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64  th the C-API and
183e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
183f0 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a  n are disabled..
18400 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 20  ** If the first 
18410 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20  argument is -1, 
18420 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20  then no changes 
18430 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74  are made to stat
18440 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a  e of either the.
18450 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20  ** C-API or the 
18460 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
18470 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18480 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
18490 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
184a0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
184b0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
184c0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
184d0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  ther [sqlite3_lo
184e0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
184f0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20  interface.** is 
18500 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
18510 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  led following th
18520 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18530 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18540 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20  ay.** be a NULL 
18550 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63  pointer, in whic
18560 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18570 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18580 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  ported back..** 
18590 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
185a0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
185b0 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a  MAINDBNAME</dt>.
185c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
185d0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
185e0 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65 20  change the name 
185f0 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64 61  of the "main" da
18600 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61  tabase.** schema
18610 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72 67  .  ^The sole arg
18620 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
18630 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74  er to a constant
18640 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20   UTF8 string.** 
18650 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d  which will becom
18660 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d 61  e the new schema
18670 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f   name in place o
18680 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69  f "main".  ^SQLi
18690 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d  te.** does not m
186a0 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
186b0 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65 6d  e new main schem
186c0 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20 73  a name string, s
186d0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
186e0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
186f0 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d 65   that the argume
18700 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  nt passed into t
18710 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70 74  his DBCONFIG opt
18720 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65 64  ion is unchanged
18730 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72 20  .** until after 
18740 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
18750 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
18760 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
18770 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18780 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c  IG_NO_CKPT_ON_CL
18790 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  OSE</dt>.** <dd>
187a0 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 61   Usually, when a
187b0 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61 6c   database in wal
187c0 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64 20   mode is closed 
187d0 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f 6d  or detached from
187e0 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   a .** database 
187f0 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20 63  handle, SQLite c
18800 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77 69  hecks if this wi
18810 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ll mean that the
18820 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a  re are now no .*
18830 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 74  * connections at
18840 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74 61   all to the data
18850 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74 20  base. If so, it 
18860 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63 6b  performs a check
18870 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 74  point .** operat
18880 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73 69  ion before closi
18890 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ng the connectio
188a0 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d  n. This option m
188b0 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a 2a  ay be used to.**
188c0 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20 62   override this b
188d0 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66 69  ehaviour. The fi
188e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 61  rst parameter pa
188f0 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65  ssed to this ope
18900 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20  ration.** is an 
18910 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a 65  integer - non-ze
18920 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 63 68  ro to disable ch
18930 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f  eckpoints-on-clo
18940 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68 65  se, or zero (the
18950 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f 20  .** default) to 
18960 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 68 65  enable them. The
18970 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18980 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
18990 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  o an integer.** 
189a0 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 72  into which is wr
189b0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
189c0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
189d0 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
189e0 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62 65  close.** have be
189f0 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30 20  en disabled - 0 
18a00 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  if they are not 
18a10 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20 74  disabled, 1 if t
18a20 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64  hey are..** </dd
18a30 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
18a40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18a50 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e  DBCONFIG_MAINDBN
18a60 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 31  AME            1
18a70 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61  000 /* const cha
18a80 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r* */.#define SQ
18a90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
18aa0 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20  OKASIDE         
18ab0 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64      1001 /* void
18ac0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
18ad0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18ae0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
18af0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20             1002 
18b00 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
18b10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
18b20 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
18b30 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30  IGGER        100
18b40 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  3 /* int int* */
18b50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18b60 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18b70 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31  FTS3_TOKENIZER 1
18b80 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  004 /* int int* 
18b90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18ba0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18bb0 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
18bc0 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74   1005 /* int int
18bd0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18be0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
18bf0 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20  CKPT_ON_CLOSE   
18c00 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69     1006 /* int i
18c10 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
18c20 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
18c30 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
18c40 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
18c50 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
18c60 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
18c70 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
18c80 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
18c90 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
18ca0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
18cb0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
18cc0 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
18cd0 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
18ce0 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
18cf0 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
18d00 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
18d10 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
18d20 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
18d30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18d40 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
18d50 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
18d60 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
18d70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
18d80 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
18d90 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
18da0 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  3.**.** ^Each en
18db0 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69  try in most SQLi
18dc0 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70  te tables (excep
18dd0 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52  t for [WITHOUT R
18de0 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a  OWID] tables).**
18df0 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
18e00 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
18e10 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
18e20 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
18e30 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
18e40 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
18e50 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
18e60 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
18e70 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
18e80 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
18e90 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
18ea0 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
18eb0 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
18ec0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
18ed0 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
18ee0 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
18ef0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
18f00 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
18f10 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
18f20 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
18f30 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
18f40 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
18f50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
18f60 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
18f70 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 75 73  (D) interface us
18f80 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
18f90 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20  e [rowid] of.** 
18fa0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
18fb0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
18fc0 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
18fd0 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
18fe0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
18ff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19000 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20  ion D. ^Inserts 
19010 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
19020 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
19030 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e  not.** recorded.
19040 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
19050 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
19060 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68  o rowid tables h
19070 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
19080 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74  d .** on the dat
19090 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
190a0 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33   D, then sqlite3
190b0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
190c0 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a  id(D) returns .*
190d0 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73  * zero..**.** As
190e0 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73   well as being s
190f0 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  et automatically
19100 20 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73   as rows are ins
19110 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62  erted into datab
19120 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74  ase.** tables, t
19130 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19140 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
19150 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65 78  on may be set ex
19160 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b  plicitly by.** [
19170 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
19180 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19190 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74  .**.** Some virt
191a0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
191b0 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e  entations may IN
191c0 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72  SERT rows into r
191d0 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a  owid tables as.*
191e0 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74  * part of commit
191f0 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ting a transacti
19200 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73  on (e.g. to flus
19210 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74  h data accumulat
19220 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ed in memory.** 
19230 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69  to disk). In thi
19240 73 20 63 61 73 65 20 73 75 62 73 65 71 75 65 6e  s case subsequen
19250 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20  t calls to this 
19260 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20  function return 
19270 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73  the rowid.** ass
19280 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
19290 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45  se internal INSE
192a0 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77  RT operations, w
192b0 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a  hich leads to .*
192c0 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65  * unintuitive re
192d0 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74  sults. Virtual t
192e0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
192f0 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69  ions that do wri
19300 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74  te to rowid.** t
19310 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61  ables in this wa
19320 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73  y can avoid this
19330 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74   problem by rest
19340 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  oring the origin
19350 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c  al .** rowid val
19360 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ue using [sqlite
19370 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
19380 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72  t_rowid()] befor
19390 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20  e returning .** 
193a0 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75  control to the u
193b0 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ser..**.** ^(If 
193c0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
193d0 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
193e0 67 65 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f  ger then this ro
193f0 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72  utine will .** r
19400 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
19410 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
19420 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  d row as long as
19430 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
19440 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63  .** running. Onc
19450 65 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  e the trigger pr
19460 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20  ogram ends, the 
19470 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
19480 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
19490 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
194a0 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
194b0 20 74 68 65 20 74 72 69 67 67 65 72 20 77 61 73   the trigger was
194c0 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
194d0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
194e0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
194f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
19500 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
19510 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
19520 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
19530 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
19540 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19550 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
19560 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
19570 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
19580 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
19590 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
195a0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
195b0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
195c0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
195d0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
195e0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
195f0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
19600 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
19610 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
19620 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
19630 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
19640 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
19650 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
19660 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
19670 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
19680 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
19690 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
196a0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
196b0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
196c0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
196d0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
196e0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
196f0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
19700 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
19710 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
19720 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
19730 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
19740 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
19750 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
19760 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
19770 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
19780 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
19790 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
197a0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
197b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
197c0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
197d0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
197e0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
197f0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
19800 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
19810 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
19820 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
19830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19840 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
19850 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
19860 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
19870 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
19880 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
19890 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
198a0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
198b0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
198c0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
198d0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
198e0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
198f0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
19900 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
19910 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
19920 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
19930 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
19940 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
19950 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
19960 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
19970 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19980 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 68  CAPI3REF: Set th
19990 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  e Last Insert Ro
199a0 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45  wid value..** ME
199b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
199c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
199d0 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
199e0 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68  rowid(D, R) meth
199f0 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70  od allows the ap
19a00 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
19a10 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  set the value re
19a20 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  turned by callin
19a30 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  g sqlite3_last_i
19a40 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74  nsert_rowid(D) t
19a50 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20  o R .** without 
19a60 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20  inserting a row 
19a70 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
19a80 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
19a90 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
19aa0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
19ab0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
19ac0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19ad0 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
19ae0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
19af0 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
19b00 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
19b10 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
19b20 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
19b30 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
19b40 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a  , inserted or.**
19b50 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
19b60 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
19b70 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
19b80 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
19b90 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  .** statement on
19ba0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
19bb0 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69  nnection specifi
19bc0 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70  ed by the only p
19bd0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78  arameter..** ^Ex
19be0 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
19bf0 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
19c00 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
19c10 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75   modify the valu
19c20 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
19c30 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
19c40 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e  **.** ^Only chan
19c50 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c  ges made directl
19c60 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  y by the INSERT,
19c70 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
19c80 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a  E statement are.
19c90 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20  ** considered - 
19ca0 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  auxiliary change
19cb0 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45  s caused by [CRE
19cc0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
19cd0 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f  iggers], .** [fo
19ce0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
19cf0 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20  s] or [REPLACE] 
19d00 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
19d10 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f  ution are not co
19d20 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68  unted..** .** Ch
19d30 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
19d40 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
19d50 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53  pted by .** [INS
19d60 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
19d70 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  | INSTEAD OF tri
19d80 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63  ggers] are not c
19d90 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c  ounted. ^The val
19da0 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ue .** returned 
19db0 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
19dc0 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79  es() immediately
19dd0 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54   after an INSERT
19de0 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20  , UPDATE or .** 
19df0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
19e00 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69   run on a view i
19e10 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f  s always zero. O
19e20 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
19e30 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62   to real .** tab
19e40 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  les are counted.
19e50 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72  .**.** Things ar
19e60 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74  e more complicat
19e70 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65  ed if the sqlite
19e80 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
19e90 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75  tion is.** execu
19ea0 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67  ted while a trig
19eb0 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72  ger program is r
19ec0 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79  unning. This may
19ed0 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a   happen if the.*
19ee0 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74  * program uses t
19ef0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
19f00 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20  L function], or 
19f10 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61  if some other ca
19f20 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
19f30 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74  on invokes sqlit
19f40 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72  e3_changes() dir
19f50 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c  ectly. Essential
19f60 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a  ly:.** .** <ul>.
19f70 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f  **   <li> ^(Befo
19f80 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72  re entering a tr
19f90 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68  igger program th
19fa0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19fb0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71   by.**        sq
19fc0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
19fd0 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65  function is save
19fe0 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69  d. After the tri
19ff0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a  gger program .**
1a000 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69          has fini
1a010 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e  shed, the origin
1a020 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74  al value is rest
1a030 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20  ored.)^.** .**  
1a040 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61   <li> ^(Within a
1a050 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1a060 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50   each INSERT, UP
1a070 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20  DATE and DELETE 
1a080 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65  .**        state
1a090 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61  ment sets the va
1a0a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1a0b0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a0c0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f  ) .**        upo
1a0d0 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20  n completion as 
1a0e0 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73  normal. Of cours
1a0f0 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69  e, this value wi
1a100 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a  ll not include .
1a110 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68  **        any ch
1a120 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20  anges performed 
1a130 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c  by sub-triggers,
1a140 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f   as the sqlite3_
1a150 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1a160 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20       value will 
1a170 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73  be saved and res
1a180 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68  tored after each
1a190 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73   sub-trigger has
1a1a0 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e   run.)^.** </ul>
1a1b0 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65  .** .** ^This me
1a1c0 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20  ans that if the 
1a1d0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1a1e0 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c  nction (or simil
1a1f0 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62  ar) is used.** b
1a200 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45  y the first INSE
1a210 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1a220 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1a230 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
1a240 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20   it .** returns 
1a250 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74  the value as set
1a260 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e   when the callin
1a270 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61  g statement bega
1a280 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  n executing..** 
1a290 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62  ^If it is used b
1a2a0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20  y the second or 
1a2b0 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20  subsequent such 
1a2c0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1a2d0 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70   a trigger .** p
1a2e0 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75  rogram, the valu
1a2f0 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65  e returned refle
1a300 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  cts the number o
1a310 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20  f rows modified 
1a320 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69  by the .** previ
1a330 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ous INSERT, UPDA
1a340 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1a350 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
1a360 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
1a370 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
1a380 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
1a390 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
1a3a0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
1a3b0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1a3c0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
1a3d0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1a3e0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1a3f0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1a400 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1a410 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1a420 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a430 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1a440 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1a450 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1a460 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a470 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
1a480 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1a490 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
1a4a0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a4b0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1a4c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
1a4d0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
1a4e0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
1a4f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1a500 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1a510 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
1a520 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
1a530 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
1a540 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
1a550 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
1a560 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
1a570 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
1a580 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
1a590 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
1a5a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a5b0 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
1a5c0 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
1a5d0 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
1a5e0 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
1a5f0 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
1a600 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1a610 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1a620 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
1a630 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
1a640 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1a650 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1a660 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
1a670 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
1a680 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
1a690 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
1a6a0 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
1a6b0 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
1a6c0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1a6d0 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
1a6e0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1a6f0 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
1a700 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
1a710 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
1a720 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
1a730 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
1a740 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1a750 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
1a760 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
1a770 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1a780 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1a790 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1a7a0 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
1a7b0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1a7c0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1a7d0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1a7e0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1a7f0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1a800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a810 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1a820 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a830 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1a840 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
1a850 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
1a860 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1a870 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1a880 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
1a890 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
1a8a0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1a8b0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
1a8c0 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
1a8d0 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f  g Query.** METHO
1a8e0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1a8f0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1a900 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
1a910 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
1a920 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
1a930 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
1a940 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
1a950 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
1a960 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
1a970 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
1a980 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
1a990 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
1a9a0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
1a9b0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
1a9c0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
1a9d0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
1a9e0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
1a9f0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
1aa00 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
1aa10 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
1aa20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
1aa30 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
1aa40 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
1aa50 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
1aa60 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1aa70 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
1aa80 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
1aa90 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
1aaa0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1aab0 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
1aac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1aad0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
1aae0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
1aaf0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
1ab00 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
1ab10 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
1ab20 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
1ab30 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
1ab40 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
1ab50 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
1ab60 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1ab70 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
1ab80 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
1ab90 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
1aba0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
1abb0 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
1abc0 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
1abd0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
1abe0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
1abf0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
1ac00 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
1ac10 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
1ac20 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
1ac30 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
1ac40 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
1ac50 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1ac60 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
1ac70 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
1ac80 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
1ac90 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
1aca0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
1acb0 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
1acc0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
1acd0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
1ace0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
1acf0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
1ad00 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
1ad10 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
1ad20 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1ad30 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
1ad40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ad50 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
1ad60 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
1ad70 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1ad80 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1ad90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1ada0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
1adb0 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
1adc0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1add0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
1ade0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
1adf0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
1ae00 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
1ae10 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
1ae20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1ae30 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
1ae40 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1ae50 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1ae60 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
1ae70 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
1ae80 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
1ae90 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
1aea0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
1aeb0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
1aec0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
1aed0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1aee0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
1aef0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
1af00 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1af10 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
1af20 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
1af30 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
1af40 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1af50 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1af60 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1af70 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1af80 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
1af90 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
1afa0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
1afb0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1afc0 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
1afd0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1afe0 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
1aff0 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
1b000 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
1b010 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
1b020 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1b030 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
1b040 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
1b050 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
1b060 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b070 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
1b080 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
1b090 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
1b0a0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
1b0b0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
1b0c0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
1b0d0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
1b0e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
1b0f0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
1b100 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
1b110 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
1b120 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
1b130 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
1b140 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
1b150 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
1b160 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
1b170 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
1b180 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
1b190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
1b1a0 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
1b1b0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
1b1c0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
1b1d0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
1b1e0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
1b1f0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
1b200 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
1b210 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
1b220 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
1b230 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
1b240 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
1b250 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
1b260 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
1b270 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
1b280 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
1b290 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
1b2a0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
1b2b0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
1b2c0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
1b2d0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
1b2e0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
1b2f0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
1b300 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
1b310 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
1b320 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
1b330 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
1b340 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
1b350 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
1b360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1b370 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
1b380 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
1b390 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
1b3a0 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
1b3b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
1b3c0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
1b3d0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
1b3e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1b3f0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
1b400 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
1b410 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
1b420 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
1b430 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
1b440 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
1b450 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
1b460 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
1b470 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
1b480 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1b490 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
1b4a0 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
1b4b0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1b4c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
1b4d0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
1b4e0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
1b4f0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
1b500 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
1b510 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
1b520 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
1b530 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
1b540 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
1b550 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1b560 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
1b570 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
1b580 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1b590 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
1b5a0 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
1b5b0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1b5c0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1b5d0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
1b5e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b5f0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
1b600 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
1b610 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1b620 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
1b630 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1b640 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
1b650 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
1b660 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
1b670 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1b680 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
1b690 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
1b6a0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
1b6b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
1b6c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b6d0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
1b6e0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
1b6f0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
1b700 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1b710 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
1b720 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e  lback} {busy han
1b730 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  dler}.** METHOD:
1b740 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1b750 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1b760 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20  _handler(D,X,P) 
1b770 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
1b780 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1b790 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74   X.** that might
1b7a0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1b7b0 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
1b7c0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
1b7d0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  pt is made to ac
1b7e0 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20  cess a database 
1b7f0 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64  table associated
1b800 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61   with.** [databa
1b810 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1b820 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68   when another th
1b830 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
1b840 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65  ss has the table
1b850 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20   locked..** The 
1b860 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1b870 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  dler() interface
1b880 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   is used to impl
1b890 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65  ement.** [sqlite
1b8a0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1b8b0 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75  ] and [PRAGMA bu
1b8c0 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a  sy_timeout]..**.
1b8d0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
1b8e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1b8f0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
1b900 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  USY].** is retur
1b910 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
1b920 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
1b930 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
1b940 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1b950 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
1b960 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
1b970 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
1b980 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
1b990 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
1b9a0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1b9b0 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
1b9c0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
1b9d0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
1b9e0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
1b9f0 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
1ba00 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1ba10 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
1ba20 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
1ba30 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
1ba40 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
1ba50 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
1ba60 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
1ba70 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
1ba80 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
1ba90 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73  invoked previous
1baa0 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ly for the same 
1bab0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
1bac0 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
1bad0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1bae0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
1baf0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
1bb00 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
1bb10 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1bb20 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
1bb30 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USY] is returned
1bb40 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1bb50 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  cation..** ^If t
1bb60 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1bb70 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1bb80 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
1bb90 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
1bba0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1bbb0 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63  base and the cyc
1bbc0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
1bbd0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
1bbe0 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
1bbf0 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
1bc00 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
1bc10 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
1bc20 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
1bc30 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
1bc40 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
1bc50 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
1bc60 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
1bc70 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
1bc80 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
1bc90 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
1bca0 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
1bcb0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74  QLITE_BUSY].** t
1bcc0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1bcd0 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  n instead of inv
1bce0 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75  oking the .** bu
1bcf0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
1bd00 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
1bd10 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
1bd20 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1bd30 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
1bd40 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
1bd50 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1bd60 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
1bd70 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
1bd80 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1bd90 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
1bda0 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
1bdb0 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
1bdc0 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
1bdd0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
1bde0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
1bdf0 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
1be00 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1be10 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1be20 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
1be30 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
1be40 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
1be50 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1be60 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
1be70 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
1be80 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
1be90 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
1bea0 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
1beb0 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
1bec0 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
1bed0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
1bee0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
1bef0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
1bf00 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
1bf10 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
1bf20 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1bf30 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
1bf40 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
1bf50 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
1bf60 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
1bf70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
1bf80 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
1bf90 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1bfa0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1bfb0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1bfc0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1bfd0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
1bfe0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
1bff0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
1c000 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
1c010 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
1c020 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
1c030 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
1c040 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
1c050 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
1c060 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
1c070 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b   or evaluating [
1c080 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1c090 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e  out=N] will chan
1c0a0 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ge the.** busy h
1c0b0 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20  andler and thus 
1c0c0 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f  clear any previo
1c0d0 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61  usly set busy ha
1c0e0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
1c0f0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
1c100 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
1c110 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
1c120 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
1c130 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c140 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1c150 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1c160 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
1c170 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  s,.** the busy h
1c180 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65  andler is not re
1c190 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75  entrant.  Any su
1c1a0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
1c1b0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
1c1c0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
1c1d0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
1c1e0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
1c1f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1c200 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
1c210 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c220 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
1c230 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c240 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
1c250 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1c260 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76  qlite3*,int(*)(v
1c270 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29  oid*,int),void*)
1c280 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c290 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
1c2a0 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meout.** METHOD:
1c2b0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1c2c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1c2d0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
1c2e0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
1c2f0 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
1c300 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
1c310 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
1c320 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
1c330 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
1c340 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
1c350 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
1c360 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
1c370 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1c380 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1c390 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
1c3a0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
1c3b0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
1c3c0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1c3d0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
1c3e0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
1c3f0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
1c400 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
1c410 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
1c420 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
1c430 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
1c440 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1c450 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
1c460 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
1c470 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
1c480 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
1c490 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
1c4a0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1c4b0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1c4c0 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
1c4d0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1c4e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c4f0 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d  ] at any given m
1c500 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
1c510 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
1c520 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
1c530 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
1c540 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
1c550 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
1c560 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
1c570 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
1c580 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
1c590 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  eared.)^.**.** S
1c5a0 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d  ee also:  [PRAGM
1c5b0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a  A busy_timeout].
1c5c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1c5d0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
1c5e0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
1c5f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c600 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
1c610 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
1c620 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48   Queries.** METH
1c630 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c640 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
1c650 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
1c660 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
1c670 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1c680 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
1c690 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
1c6a0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
1c6b0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
1c6c0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
1c6d0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
1c6e0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
1c6f0 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
1c700 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
1c710 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1c720 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
1c730 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
1c740 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
1c750 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
1c760 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
1c770 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
1c780 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
1c790 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
1c7a0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
1c7b0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
1c7c0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
1c7d0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
1c7e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1c7f0 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
1c800 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
1c810 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
1c820 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
1c830 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1c840 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
1c850 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1c860 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
1c870 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
1c880 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
1c890 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
1c8a0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1c8b0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
1c8c0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
1c8d0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
1c8e0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
1c8f0 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
1c900 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1c910 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1c920 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
1c930 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
1c940 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
1c950 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
1c960 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
1c970 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
1c980 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
1c990 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
1c9a0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
1c9b0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
1c9c0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1c9d0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1c9e0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
1c9f0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1ca00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1ca10 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
1ca20 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
1ca30 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
1ca40 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
1ca50 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
1ca60 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
1ca70 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
1ca80 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
1ca90 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1caa0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
1cab0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
1cac0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
1cad0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
1cae0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
1caf0 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
1cb00 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1cb10 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
1cb20 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
1cb30 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
1cb40 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1cb50 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1cb60 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
1cb70 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
1cb80 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
1cb90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
1cba0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
1cbb0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
1cbc0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
1cbd0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
1cbe0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
1cbf0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1cc00 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
1cc10 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
1cc20 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
1cc30 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
1cc40 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
1cc50 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
1cc60 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
1cc70 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1cc80 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1cc90 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
1cca0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
1ccb0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
1ccc0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
1ccd0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1cce0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
1ccf0 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
1cd00 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
1cd10 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
1cd20 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
1cd30 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1cd40 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
1cd50 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1cd60 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
1cd70 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1cd80 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
1cd90 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
1cda0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
1cdb0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
1cdc0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
1cdd0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
1cde0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1cdf0 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
1ce00 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1ce10 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
1ce20 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1ce30 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
1ce40 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
1ce50 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
1ce60 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
1ce70 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1ce80 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1ce90 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
1cea0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
1ceb0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
1cec0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1ced0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
1cee0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
1cef0 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
1cf00 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
1cf10 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
1cf20 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
1cf30 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
1cf40 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1cf50 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
1cf60 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
1cf70 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
1cf80 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1cf90 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
1cfa0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
1cfb0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
1cfc0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
1cfd0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
1cfe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
1cff0 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
1d000 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
1d010 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
1d020 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
1d030 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
1d040 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
1d050 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
1d060 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
1d070 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1d080 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
1d090 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1d0a0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
1d0b0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
1d0c0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d0d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1d0e0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
1d0f0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
1d100 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1d110 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
1d120 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
1d130 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
1d140 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
1d150 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
1d160 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
1d170 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
1d180 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
1d190 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
1d1a0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
1d1b0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
1d1c0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
1d1d0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
1d1e0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
1d1f0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
1d200 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
1d210 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
1d220 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
1d230 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1d240 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
1d250 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
1d260 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1d270 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1d280 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
1d290 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1d2a0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
1d2b0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
1d2c0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1d2d0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
1d2e0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
1d2f0 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
1d300 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
1d310 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
1d320 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
1d330 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1d340 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
1d350 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1d360 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
1d370 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
1d380 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
1d390 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
1d3a0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
1d3b0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
1d3c0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
1d3d0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
1d3e0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
1d3f0 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1d400 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1d410 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1d420 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1d430 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1d440 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1d450 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1d460 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1d470 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1d480 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1d490 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1d4a0 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
1d4b0 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
1d4c0 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
1d4d0 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74  mmon K&R formatt
1d4e0 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20  ing options,.** 
1d4f0 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
1d500 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
1d510 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69  d formats, detai
1d520 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f  led below..** No
1d530 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20  te that some of 
1d540 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65  the more obscure
1d550 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1d560 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a  ons from recent.
1d570 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61  ** C-library sta
1d580 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74  ndards are omitt
1d590 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70  ed from this imp
1d5a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a  lementation..**.
1d5b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1d5c0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1d5d0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1d5e0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1d5f0 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1d600 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1d610 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1d620 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1d630 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1d640 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1d650 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1d660 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1d670 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1d680 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1d690 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1d6a0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1d6b0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1d6c0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1d6d0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1d6e0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1d6f0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1d700 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1d710 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1d720 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1d730 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1d740 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1d750 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1d760 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1d770 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1d780 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1d790 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1d7a0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1d7b0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1d7c0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1d7d0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1d7e0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1d7f0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1d800 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1d810 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1d820 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1d830 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1d840 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1d850 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1d860 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1d870 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1d880 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1d890 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1d8a0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1d8b0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d8c0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1d8d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1d8e0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1d8f0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1d900 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1d910 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1d920 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1d930 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1d940 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1d950 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1d960 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1d970 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1d980 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1d990 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1d9a0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1d9b0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1d9c0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1d9d0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1d9e0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1d9f0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1da00 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1da10 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1da20 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1da30 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1da40 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1da50 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1da60 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1da70 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1da80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1da90 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1daa0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1dab0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1dac0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1dad0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1dae0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1daf0 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1db00 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1db10 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1db20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1db30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1db40 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1db50 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1db60 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1db70 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1db80 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1db90 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1dba0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1dbb0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1dbc0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1dbd0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1dbe0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1dbf0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1dc00 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1dc10 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1dc20 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1dc30 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1dc40 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1dc50 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25  e "%q", "%Q", "%
1dc60 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  w" and "%z" opti
1dc70 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1dc80 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1dc90 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1dca0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1dcb0 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1dcc0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1dcd0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1dce0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1dcf0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1dd00 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1dd10 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1dd20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1dd30 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1dd40 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1dd50 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1dd60 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1dd70 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1dd80 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1dd90 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1dda0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1ddb0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1ddc0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1ddd0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1dde0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1ddf0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1de00 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1de10 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1de20 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1de30 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1de40 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1de50 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1de60 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1de70 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1de80 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1de90 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1dea0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1deb0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1dec0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1ded0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1dee0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1def0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1df00 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1df10 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1df20 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1df30 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1df40 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1df50 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1df60 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1df70 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1df80 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1df90 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1dfa0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1dfb0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1dfc0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1dfd0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1dfe0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1dff0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1e000 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1e010 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1e020 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1e030 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1e040 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1e050 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1e060 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1e070 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1e080 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1e090 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e0a0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1e0b0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1e0c0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1e0d0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1e0e0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e0f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1e100 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1e110 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1e120 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1e130 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1e140 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1e150 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1e160 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1e170 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1e180 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1e190 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1e1a0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1e1b0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1e1c0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1e1d0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1e1e0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1e1f0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1e200 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1e210 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1e220 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1e230 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1e240 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1e250 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1e260 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1e270 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1e280 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1e290 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1e2a0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1e2b0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e2c0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1e2d0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1e2e0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e2f0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1e300 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1e310 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1e320 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1e330 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1e340 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1e350 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e360 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1e370 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1e380 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1e390 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1e3a0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1e3b0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1e3c0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1e3d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1e3e0 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61  ^(The "%w" forma
1e3f0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1e400 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74  like "%q" except
1e410 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73   that it expects
1e420 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69   to.** be contai
1e430 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
1e440 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64  e-quotes instead
1e450 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65   of single quote
1e460 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63  s, and it.** esc
1e470 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d  apes the double-
1e480 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20  quote character 
1e490 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73  instead of the s
1e4a0 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63  ingle-quote.** c
1e4b0 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65  haracter.)^  The
1e4c0 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1e4d0 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e   option is inten
1e4e0 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69  ded for safely i
1e4f0 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c  nserting.** tabl
1e500 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  e and column nam
1e510 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72  es into a constr
1e520 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  ucted SQL statem
1e530 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ent..**.** ^(The
1e540 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1e550 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1e560 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1e570 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1e580 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1e590 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1e5a0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1e5b0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1e5c0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1e5d0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1e5e0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1e5f0 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
1e600 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1e610 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1e620 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1e630 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1e640 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
1e650 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1e660 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1e670 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1e680 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1e690 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1e6a0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1e6b0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1e6c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1e6d0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1e6e0 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1e6f0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1e700 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1e710 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1e720 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1e730 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1e740 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1e750 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1e760 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1e770 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1e780 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1e790 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1e7a0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1e7b0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1e7c0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1e7d0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1e7e0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1e7f0 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1e800 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1e810 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1e820 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1e830 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1e840 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1e850 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1e860 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1e870 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1e880 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1e890 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1e8a0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1e8b0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1e8c0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1e8d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1e8e0 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1e8f0 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1e900 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1e910 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1e920 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1e930 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1e940 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1e950 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
1e960 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e  lite3_malloc64(N
1e970 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20  ) routine works 
1e980 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c  just like.** sql
1e990 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65  ite3_malloc(N) e
1e9a0 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1e9b0 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62  an unsigned 64-b
1e9c0 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  it integer inste
1e9d0 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65  ad.** of a signe
1e9e0 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  d 32-bit integer
1e9f0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1ea00 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1ea10 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1ea20 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1ea30 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1ea40 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1ea50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1ea60 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1ea70 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1ea80 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1ea90 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1eaa0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1eab0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1eac0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1ead0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1eae0 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1eaf0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1eb00 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1eb10 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1eb20 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1eb30 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1eb40 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1eb50 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1eb60 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1eb70 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1eb80 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1eb90 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1eba0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1ebb0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1ebc0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1ebd0 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1ebe0 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1ebf0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1ec00 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1ec10 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1ec20 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1ec30 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1ec40 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1ec50 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1ec60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1ec70 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1ec80 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1ec90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1eca0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65  ealloc(X,N) inte
1ecb0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1ecc0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1ecd0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1ece0 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74  ation X to be at
1ecf0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a   least N bytes..
1ed00 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72  ** ^If the X par
1ed10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1ed20 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a  3_realloc(X,N).*
1ed30 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
1ed40 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
1ed50 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
1ed60 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
1ed70 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ed80 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  N)..** ^If the N
1ed90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1eda0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1edb0 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  N) is zero or.**
1edc0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1edd0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1ede0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1edf0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1ee00 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a  lite3_free(X)..*
1ee10 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1ee20 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1ee30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1ee40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ee50 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1ee60 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1ee70 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  or NULL if insuf
1ee80 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1ee90 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
1eea0 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1eeb0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1eec0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1eed0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1eee0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1eef0 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1ef00 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1ef10 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1ef20 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1ef30 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ef40 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72  (X,N) and the pr
1ef50 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1ef60 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1ef70 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ef80 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  X,N) returns NUL
1ef90 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74  L and N is posit
1efa0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ive, then the.**
1efb0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1efc0 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  n is not freed..
1efd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1efe0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e  e3_realloc64(X,N
1eff0 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  ) interfaces wor
1f000 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ks the same as.*
1f010 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * sqlite3_reallo
1f020 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68  c(X,N) except th
1f030 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74  at N is a 64-bit
1f040 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
1f050 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
1f060 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  a 32-bit signed 
1f070 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
1f080 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79  If X is a memory
1f090 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76   allocation prev
1f0a0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
1f0b0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1f0c0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1f0d0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71  3_malloc64(), sq
1f0e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1f0f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1f100 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a  loc64(), then.**
1f110 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1f120 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  ) returns the si
1f130 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72  ze of that memor
1f140 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20  y allocation in 
1f150 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76  bytes..** ^The v
1f160 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1f170 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1f180 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  ) might be large
1f190 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65  r than the numbe
1f1a0 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65  r.** of bytes re
1f1b0 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77  quested when X w
1f1c0 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  as allocated.  ^
1f1d0 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70  If X is a NULL p
1f1e0 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73  ointer then.** s
1f1f0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1f200 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49  returns zero.  I
1f210 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f  f X points to so
1f220 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20  mething that is 
1f230 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e  not.** the begin
1f240 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ning of memory a
1f250 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66  llocation, or if
1f260 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20   it points to a 
1f270 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69  formerly.** vali
1f280 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
1f290 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77  ion that has now
1f2a0 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65   been freed, the
1f2b0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
1f2c0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69  * of sqlite3_msi
1f2d0 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e  ze(X) is undefin
1f2e0 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20  ed and possibly 
1f2f0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
1f300 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1f310 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1f320 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33  alloc(), sqlite3
1f330 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  _realloc(),.** s
1f340 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1f350 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
1f360 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73  ealloc64().** is
1f370 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
1f380 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
1f390 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
1f3a0 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
1f3b0 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
1f3c0 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
1f3d0 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
1f3e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1f3f0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
1f400 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
1f410 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
1f420 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
1f430 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
1f440 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
1f450 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
1f460 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
1f470 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
1f480 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
1f490 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
1f4a0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
1f4b0 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
1f4c0 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
1f4d0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
1f4e0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
1f4f0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1f500 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
1f510 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
1f520 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
1f530 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
1f540 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
1f550 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
1f560 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
1f570 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1f580 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
1f590 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
1f5a0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
1f5b0 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1f5c0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
1f5d0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
1f5e0 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
1f5f0 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
1f600 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
1f610 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
1f620 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
1f630 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1f640 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
1f650 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
1f660 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1f670 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1f680 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1f690 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1f6a0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1f6b0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1f6c0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1f6d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1f6e0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1f6f0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1f700 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1f710 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1f720 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1f730 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1f740 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1f750 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1f760 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1f770 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1f780 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1f790 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1f7a0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1f7b0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1f7c0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1f7d0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1f7e0 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1f7f0 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1f800 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1f810 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1f820 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1f830 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
1f840 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1f850 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1f860 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1f870 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1f880 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1f890 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
1f8a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1f8b0 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
1f8c0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1f8d0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1f8e0 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  void*);.sqlite3_
1f8f0 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  uint64 sqlite3_m
1f900 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
1f910 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1f920 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1f930 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1f940 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1f950 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1f960 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1f970 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1f980 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1f990 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1f9a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1f9b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1f9c0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1f9d0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1f9e0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1f9f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1fa00 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1fa10 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1fa20 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1fa30 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1fa40 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1fa50 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1fa60 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1fa70 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1fa80 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1fa90 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1faa0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1fab0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1fac0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1fad0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1fae0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1faf0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1fb00 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1fb10 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1fb20 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1fb30 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1fb40 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1fb50 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1fb60 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1fb70 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1fb80 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1fb90 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1fba0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1fbb0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1fbc0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1fbd0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1fbe0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1fbf0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1fc00 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1fc10 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1fc20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1fc30 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1fc40 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1fc50 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1fc60 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1fc70 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1fc80 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1fc90 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1fca0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1fcb0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1fcc0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1fcd0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1fce0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1fcf0 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1fd00 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1fd10 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1fd20 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1fd30 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1fd40 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
1fd50 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1fd60 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1fd70 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
1fd80 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1fd90 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1fda0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1fdb0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1fdc0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1fdd0 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1fde0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
1fdf0 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
1fe00 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
1fe10 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
1fe20 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
1fe30 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
1fe40 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
1fe50 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
1fe60 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
1fe70 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
1fe80 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
1fe90 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1fea0 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
1feb0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
1fec0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
1fed0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
1fee0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
1fef0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
1ff00 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1ff10 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
1ff20 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
1ff30 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
1ff40 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
1ff50 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
1ff60 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
1ff70 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
1ff80 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
1ff90 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68  buffer P..** ^Th
1ffa0 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61  e P parameter ca
1ffb0 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n be a NULL poin
1ffc0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
1ffd0 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20  his routine has 
1ffe0 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75  not been previou
1fff0 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66  sly called or if
20000 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a   the previous.**
20010 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73   call had N less
20020 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e   than one or a N
20030 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
20040 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47  P, then the PRNG
20050 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73   is.** seeded us
20060 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
20070 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65  btained from the
20080 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
20090 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65  hod of.** the de
200a0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
200b0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
200c0 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
200d0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
200e0 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
200f0 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61   1 or more and a
20100 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74  .** non-NULL P t
20110 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72  hen the pseudo-r
20120 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
20130 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
20140 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
20150 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
20160 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
20170 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
20180 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
20190 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
201a0 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
201b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
201c0 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
201d0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
201e0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
201f0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
20200 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
20210 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
20220 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20230 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
20240 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
20250 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
20260 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
20270 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
20280 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
20290 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
202a0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
202b0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
202c0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
202d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
202e0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
202f0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
20300 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
20310 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
20320 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
20330 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
20340 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
20350 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
20360 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
20370 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
20380 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
20390 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
203a0 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
203b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
203c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
203d0 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
203e0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
203f0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
20400 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20410 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
20420 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
20430 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
20440 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
20450 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
20460 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
20470 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
20480 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
20490 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
204a0 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
204b0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
204c0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
204d0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
204e0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
204f0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
20500 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
20510 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20520 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
20530 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
20540 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
20550 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
20560 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
20570 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
20580 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
20590 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
205a0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
205b0 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
205c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
205d0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
205e0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
205f0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
20600 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
20610 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
20620 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
20630 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
20640 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
20650 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
20660 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
20670 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
20680 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20690 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
206a0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
206b0 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
206c0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
206d0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
206e0 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
206f0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
20700 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
20710 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
20720 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
20730 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20740 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
20750 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
20760 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
20770 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
20780 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
20790 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
207a0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
207b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
207c0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
207d0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
207e0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
207f0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
20800 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
20810 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
20820 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
20830 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
20840 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
20850 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
20860 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
20870 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
20880 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
20890 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
208a0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
208b0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
208c0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
208d0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
208e0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
208f0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
20900 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
20910 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
20920 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
20930 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
20940 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
20950 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
20960 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
20970 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
20980 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
20990 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
209a0 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
209b0 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
209c0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
209d0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
209e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
209f0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
20a00 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
20a10 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
20a20 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
20a30 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
20a40 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
20a50 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
20a60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20a70 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
20a80 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
20a90 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
20aa0 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
20ab0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
20ac0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
20ad0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
20ae0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
20af0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
20b00 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
20b10 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
20b20 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
20b30 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
20b40 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
20b50 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
20b60 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
20b70 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
20b80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
20b90 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
20ba0 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
20bb0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
20bc0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
20bd0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
20be0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
20bf0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
20c00 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
20c10 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
20c20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
20c30 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
20c40 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
20c50 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
20c60 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
20c70 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
20c80 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
20c90 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
20ca0 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
20cb0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
20cc0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
20cd0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
20ce0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
20cf0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
20d00 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
20d10 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
20d20 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
20d30 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
20d40 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
20d50 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
20d60 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
20d70 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
20d80 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
20d90 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
20da0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
20db0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
20dc0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
20dd0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
20de0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
20df0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
20e00 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
20e10 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
20e20 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
20e30 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
20e40 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
20e50 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
20e60 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
20e70 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
20e80 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
20e90 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
20ea0 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
20eb0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
20ec0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
20ed0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
20ee0 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
20ef0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
20f00 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
20f10 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
20f20 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
20f30 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
20f40 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
20f50 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
20f60 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
20f70 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
20f80 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
20f90 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
20fa0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20fb0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
20fc0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
20fd0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
20fe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20ff0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
21000 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21010 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
21020 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
21030 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
21040 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21050 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
21060 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
21070 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
21080 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
21090 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
210a0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
210b0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
210c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
210d0 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
210e0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
210f0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
21100 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
21110 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
21120 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
21130 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
21140 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
21150 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
21160 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
21170 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
21180 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
21190 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
211a0 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
211b0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
211c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
211d0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
211e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
211f0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
21200 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
21210 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
21220 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
21230 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
21240 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
21250 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
21260 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
21270 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
21280 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
21290 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
212a0 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
212b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
212c0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
212d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
212e0 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
212f0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
21300 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
21310 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
21320 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
21330 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
21340 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
21350 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
21360 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
21370 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
21380 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
21390 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
213a0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
213b0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
213c0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
213d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
213e0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
213f0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
21400 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
21410 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
21420 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
21430 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
21440 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
21450 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
21460 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
21470 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
21480 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
21490 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
214a0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
214b0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
214c0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
214d0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
214e0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
214f0 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
21500 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
21510 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
21520 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
21530 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
21540 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
21550 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
21560 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
21570 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21580 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
21590 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
215a0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
215b0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
215c0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
215d0 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
215e0 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
215f0 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
21600 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
21610 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
21620 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
21630 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
21640 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21650 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
21660 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
21670 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
21680 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
21690 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
216a0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
216b0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
216c0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
216d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
216e0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
216f0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
21700 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
21710 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
21720 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
21730 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
21740 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
21750 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
21760 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21770 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
21780 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
21790 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
217a0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
217b0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
217c0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
217d0 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
217e0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
217f0 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
21800 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
21810 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
21820 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
21830 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
21840 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
21850 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
21860 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
21870 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
21880 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
21890 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
218a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
218b0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
218c0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
218d0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
218e0 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
218f0 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
21900 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
21910 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21920 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
21930 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
21940 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
21950 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
21960 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
21970 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
21980 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
21990 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
219a0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
219b0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
219c0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
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 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
21a00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
21a10 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
21a20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21a30 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
21a40 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
21a50 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
21a60 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21a70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21a80 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
21a90 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
21aa0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21ab0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21ac0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21ad0 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
21ae0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
21af0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
21b00 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21b10 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21b20 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
21b30 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
21b40 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21b50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21b60 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21b70 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
21b80 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
21b90 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
21ba0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21bb0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21bc0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
21bd0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
21be0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21bf0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21c00 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
21c10 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
21c20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
21c30 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21c40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21c50 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
21c60 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
21c70 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
21c80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21c90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21ca0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
21cb0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
21cc0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21cd0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21ce0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21cf0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
21d00 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
21d10 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
21d20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21d30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21d40 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
21d50 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
21d60 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21d70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21d80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21d90 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
21da0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
21db0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
21dc0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21dd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21de0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
21df0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
21e00 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21e10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21e30 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
21e40 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
21e50 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
21e60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21e70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21e80 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
21e90 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
21ea0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
21eb0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
21ed0 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
21ee0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
21ef0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
21f00 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21f10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21f20 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
21f30 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
21f40 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
21f50 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21f60 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
21f70 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
21f80 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
21f90 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21fa0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21fb0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
21fc0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
21fd0 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
21fe0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
21ff0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
22000 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
22010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
22020 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
22030 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
22040 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
22050 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
22060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
22070 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
22080 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22090 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
220a0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
220b0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
220c0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
220d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
220e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
220f0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
22100 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
22110 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22120 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
22130 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22140 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
22150 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
22160 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
22170 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22180 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22190 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
221a0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
221b0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
221c0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
221d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
221e0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
221f0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
22200 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
22210 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22220 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22230 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
22240 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
22250 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
22260 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22270 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22280 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
22290 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
222a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
222b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
222c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
222d0 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
222e0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
222f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
22300 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
22310 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22320 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
22330 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
22340 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
22350 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
22360 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
22370 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
22380 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
22390 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
223a0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
223b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
223c0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
223d0 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
223e0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
223f0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
22400 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
22410 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
22420 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
22430 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
22440 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
22450 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
22460 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
22470 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
22480 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
22490 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
224a0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
224b0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  g Functions.** M
224c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
224d0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
224e0 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74  nes are deprecat
224f0 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
22500 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
22510 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e   interface.** in
22520 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75  stead of the rou
22530 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20  tines described 
22540 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  here..**.** Thes
22550 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
22560 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
22570 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
22580 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
22590 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
225a0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
225b0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
225c0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
225d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
225e0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
225f0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
22600 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
22610 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
22620 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
22630 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
22640 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
22650 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
22660 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22670 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
22680 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
22690 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
226a0 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
226b0 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
226c0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
226d0 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
226e0 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
226f0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
22700 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
22710 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
22720 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
22730 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
22740 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
22750 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
22760 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
22770 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
22780 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
22790 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
227a0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** The [SQLITE_T
227b0 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
227c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
227d0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
227e0 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65   to limit.** the
227f0 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e   length of [boun
22800 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70  d parameter] exp
22810 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75  ansion in the ou
22820 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  tput of sqlite3_
22830 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  trace()..**.** ^
22840 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
22850 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
22860 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
22870 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
22880 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
22890 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
228a0 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
228b0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
228c0 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
228d0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
228e0 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
228f0 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
22900 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
22910 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
22920 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
22930 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
22940 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
22950 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
22960 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
22970 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
22980 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
22990 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
229a0 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
229b0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
229c0 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
229d0 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
229e0 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
229f0 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
22a00 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
22a10 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
22a20 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
22a30 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
22a40 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
22a50 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
22a60 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
22a70 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
22a80 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
22a90 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
22aa0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
22ab0 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
22ac0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
22ad0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  .*/.SQLITE_DEPRE
22ae0 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69  CATED void *sqli
22af0 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
22b00 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72  3*,.   void(*xTr
22b10 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
22b20 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
22b30 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
22b40 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
22b50 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
22b60 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
22b70 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
22b80 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
22b90 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
22ba0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22bb0 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e  : SQL Trace Even
22bc0 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
22bd0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43  RDS: SQLITE_TRAC
22be0 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  E.**.** These co
22bf0 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79  nstants identify
22c00 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e   classes of even
22c10 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d  ts that can be m
22c20 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e  onitored.** usin
22c30 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  g the [sqlite3_t
22c40 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69  race_v2()] traci
22c50 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74  ng logic.  The t
22c60 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
22c70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
22c80 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f  ce_v2()] is an O
22c90 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  R-ed combination
22ca0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
22cb0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
22cc0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20  ing constants.  
22cd0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
22ce0 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
22cf0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
22d00 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
22d10 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  wing constants..
22d20 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e  **.** New tracin
22d30 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  g constants may 
22d40 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
22d50 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
22d60 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c  ** ^A trace call
22d70 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72  back has four ar
22d80 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61  guments: xCallba
22d90 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20  ck(T,C,P,X)..** 
22da0 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20  ^The T argument 
22db0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e  is one of the in
22dc0 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73  teger type codes
22dd0 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20   above..** ^The 
22de0 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
22df0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
22e00 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ext pointer pass
22e10 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
22e20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
22e30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
22e40 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  e_v2()]..** The 
22e50 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74  P and X argument
22e60 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77  s are pointers w
22e70 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65  hose meanings de
22e80 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a  pend on T..**.**
22e90 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
22ea0 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c  E_TRACE_STMT]] <
22eb0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
22ec0 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  STMT</dt>.** <dd
22ed0 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
22ee0 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20  E_STMT callback 
22ef0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
22f00 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
22f10 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65  ment.** first be
22f20 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  gins running and
22f30 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68   possibly at oth
22f40 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20  er times during 
22f50 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e  the.** execution
22f60 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
22f70 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68   statement, such
22f80 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74   as at the start
22f90 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67   of each.** trig
22fa0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20  ger subprogram. 
22fb0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
22fc0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
22fd0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
22fe0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
22ff0 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e X argument is 
23000 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
23010 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69  tring which.** i
23020 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64  s the unexpanded
23030 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65   SQL text of the
23040 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
23050 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f  ent or an SQL co
23060 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69  mment .** that i
23070 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76  ndicates the inv
23080 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69  ocation of a tri
23090 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c  gger.  ^The call
230a0 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65  back can compute
230b0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78  .** the same tex
230c0 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  t that would hav
230d0 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20  e been returned 
230e0 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  by the legacy [s
230f0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a  qlite3_trace()].
23100 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  ** interface by 
23110 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75  using the X argu
23120 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69  ment when X begi
23130 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64  ns with "--" and
23140 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71   invoking.** [sq
23150 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
23160 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65  ql(P)] otherwise
23170 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
23180 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d  _TRACE_PROFILE]]
23190 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
231a0 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a  E_PROFILE</dt>.*
231b0 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
231c0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
231d0 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73  allback provides
231e0 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74   approximately t
231f0 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72  he same.** infor
23200 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f  mation as is pro
23210 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71  vided by the [sq
23220 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
23230 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54   callback..** ^T
23240 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
23250 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23260 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
23270 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a  ement] and the.*
23280 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  * X argument poi
23290 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20  nts to a 64-bit 
232a0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
232b0 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f   the estimated o
232c0 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  f.** the number 
232d0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68  of nanosecond th
232e0 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
232f0 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
23300 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53  o run..** ^The S
23310 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
23320 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ILE callback is 
23330 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
23340 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
23350 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  hes..**.** [[SQL
23360 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20  ITE_TRACE_ROW]] 
23370 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
23380 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ROW</dt>.** <dd
23390 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
233a0 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69  E_ROW callback i
233b0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
233c0 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  er a prepared.**
233d0 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72   statement gener
233e0 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f  ates a single ro
233f0 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a  w of result.  .*
23400 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
23410 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23420 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
23430 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74  statement] and t
23440 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74  he.** X argument
23450 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a   is unused..**.*
23460 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
23470 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c  _CLOSE]] <dt>SQL
23480 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c  ITE_TRACE_CLOSE<
23490 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
234a0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
234b0 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  SE callback is i
234c0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61  nvoked when a da
234d0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
234e0 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20  tion closes..** 
234f0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
23500 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23510 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
23520 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74  nnection] object
23530 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72  .** and the X ar
23540 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64  gument is unused
23550 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
23560 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
23570 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78  CE_STMT       0x
23580 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
23590 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
235a0 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20     0x02.#define 
235b0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
235c0 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65          0x04.#de
235d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
235e0 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30  E_CLOSE      0x0
235f0 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
23600 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f  F: SQL Trace Hoo
23610 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  k.** METHOD: sql
23620 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
23630 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23640 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,M,X,P) interf
23650 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
23660 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
23670 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61  * function X aga
23680 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63  inst [database c
23690 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73  onnection] D, us
236a0 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73  ing property mas
236b0 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65  k M.** and conte
236c0 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e  xt pointer P.  ^
236d0 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63  If the X callbac
236e0 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20  k is.** NULL or 
236f0 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73  if the M mask is
23700 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63   zero, then trac
23710 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ing is disabled.
23720 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d    The.** M argum
23730 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
23740 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20  e bitwise OR-ed 
23750 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
23760 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b  * zero or more [
23770 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f  SQLITE_TRACE] co
23780 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nstants..**.** ^
23790 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74  Each call to eit
237a0 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63  her sqlite3_trac
237b0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
237c0 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69  race_v2() overri
237d0 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73  des .** (cancels
237e0 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c  ) any prior call
237f0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61  s to sqlite3_tra
23800 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
23810 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  trace_v2()..**.*
23820 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63  * ^The X callbac
23830 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
23840 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65  never any of the
23850 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69   events identifi
23860 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d  ed by .** mask M
23870 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e   occur.  ^The in
23880 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c  teger return val
23890 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c  ue from the call
238a0 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c  back is currentl
238b0 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68  y.** ignored, th
238c0 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68  ough this may ch
238d0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72  ange in future r
238e0 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61  eleases.  Callba
238f0 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ck.** implementa
23900 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74  tions should ret
23910 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75  urn zero to ensu
23920 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74  re future compat
23930 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
23940 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  A trace callback
23950 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
23960 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
23970 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c   callback(T,C,P,
23980 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72  X)..** ^The T ar
23990 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
239a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   the [SQLITE_TRA
239b0 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73  CE].** constants
239c0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79   to indicate why
239d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61   the callback wa
239e0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  s invoked..** ^T
239f0 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
23a00 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
23a10 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a  ontext pointer..
23a20 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61  ** The P and X a
23a30 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69  rguments are poi
23a40 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e  nters whose mean
23a50 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54  ings depend on T
23a60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23a70 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69  te3_trace_v2() i
23a80 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
23a90 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20  nded to replace 
23aa0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
23ab0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
23ac0 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b  3_trace()] and [
23ad0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
23ae0 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63  )], both of whic
23af0 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61  h.** are depreca
23b00 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ted..*/.int sqli
23b10 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20  te3_trace_v2(.  
23b20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69  sqlite3*,.  unsi
23b30 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e  gned uMask,.  in
23b40 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e  t(*xCallback)(un
23b50 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69  signed,void*,voi
23b60 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  d*,void*),.  voi
23b70 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a  d *pCtx.);../*.*
23b80 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
23b90 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
23ba0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
23bb0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
23bc0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
23bd0 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
23be0 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
23bf0 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
23c00 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
23c10 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
23c20 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
23c30 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
23c40 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
23c50 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
23c60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
23c70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
23c80 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
23c90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23ca0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
23cb0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
23cc0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
23cd0 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
23ce0 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
23cf0 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
23d00 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
23d10 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
23d20 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
23d30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
23d40 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
23d50 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
23d60 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
23d70 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
23d80 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
23d90 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
23da0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
23db0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
23dc0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
23dd0 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
23de0 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
23df0 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
23e00 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
23e10 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
23e20 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
23e30 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
23e40 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
23e50 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
23e60 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
23e70 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
23e80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23e90 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
23ea0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
23eb0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
23ec0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
23ed0 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
23ee0 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
23ef0 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
23f00 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
23f10 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
23f20 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
23f30 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
23f40 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
23f50 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
23f60 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
23f70 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
23f80 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
23f90 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
23fa0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
23fb0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
23fc0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
23fd0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
23fe0 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
23ff0 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
24000 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
24010 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
24020 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
24030 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
24040 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
24050 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
24060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
24070 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
24080 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
24090 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
240a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
240b0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
240c0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
240d0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
240e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
240f0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
24100 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
24110 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
24120 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
24130 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
24140 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
24150 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
24160 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
24170 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
24180 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
24190 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
241a0 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
241b0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
241c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
241d0 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
241e0 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
241f0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
24200 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
24210 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
24220 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
24230 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
24240 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
24250 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
24260 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24270 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
24280 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
24290 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
242a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
242b0 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
242c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
242d0 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
242e0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
242f0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
24300 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
24310 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
24320 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
24330 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
24340 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
24350 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
24360 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
24370 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
24380 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
24390 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
243a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
243b0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
243c0 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
243d0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
243e0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
243f0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
24400 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
24410 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
24420 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
24430 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
24440 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
24450 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
24460 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
24470 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
24480 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
24490 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
244a0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
244b0 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
244c0 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
244d0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
244e0 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
244f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
24500 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
24510 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
24520 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
24530 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
24540 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
24550 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
24560 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
24570 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
24580 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
24590 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
245a0 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
245b0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
245c0 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
245d0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
245e0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
245f0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
24600 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
24610 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
24620 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
24630 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
24640 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
24650 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
24660 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
24670 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
24680 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
24690 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
246a0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
246b0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
246c0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
246d0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
246e0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
246f0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
24700 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
24710 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
24720 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
24730 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
24740 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
24750 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
24760 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
24770 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
24780 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
24790 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
247a0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
247b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
247c0 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
247d0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
247e0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
247f0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
24800 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
24810 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
24820 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
24830 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
24840 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
24850 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
24860 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
24870 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
24880 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
24890 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
248a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
248b0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
248c0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
248d0 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
248e0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
248f0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
24900 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
24910 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
24920 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
24930 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
24940 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
24950 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24960 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
24970 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
24980 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
24990 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
249a0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
249b0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
249c0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
249d0 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
249e0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
249f0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
24a00 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
24a10 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
24a20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
24a30 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
24a40 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24a50 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
24a60 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
24a70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
24a80 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
24a90 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
24aa0 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
24ab0 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
24ac0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
24ad0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
24ae0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
24af0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
24b00 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
24b10 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
24b20 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
24b30 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
24b40 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
24b50 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
24b60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
24b70 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
24b80 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
24b90 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
24ba0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
24bb0 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
24bc0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
24bd0 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
24be0 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
24bf0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
24c00 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
24c10 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
24c20 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
24c30 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
24c40 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
24c50 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
24c60 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
24c70 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
24c80 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
24c90 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
24ca0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
24cb0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
24cc0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
24cd0 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
24ce0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
24cf0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
24d00 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
24d10 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
24d20 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
24d30 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
24d40 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
24d50 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
24d60 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
24d70 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
24d80 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
24d90 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
24da0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
24db0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
24dc0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
24dd0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
24de0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
24df0 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
24e00 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
24e10 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
24e20 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
24e30 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
24e40 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
24e50 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24e60 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
24e70 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
24e80 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
24e90 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
24ea0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
24eb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24ec0 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
24ed0 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
24ee0 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
24ef0 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
24f00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
24f10 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
24f20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
24f30 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
24f40 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
24f50 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
24f60 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
24f70 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
24f80 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
24f90 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
24fa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24fb0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
24fc0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
24fd0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
24fe0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
24ff0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
25000 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
25010 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
25020 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
25030 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
25040 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
25050 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
25060 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
25070 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
25080 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
25090 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
250a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
250b0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
250c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
250d0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
250e0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
250f0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
25100 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
25110 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
25120 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
25130 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
25140 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
25150 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
25160 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
25170 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
25180 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
25190 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
251a0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
251b0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
251c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
251d0 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
251e0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
251f0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
25200 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
25210 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
25220 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
25230 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
25240 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
25250 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
25260 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
25270 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
25280 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
25290 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
252a0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
252b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
252c0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
252d0 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
252e0 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
252f0 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
25300 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
25310 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
25320 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
25330 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
25340 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
25350 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
25360 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
25370 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
25380 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
25390 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
253a0 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
253b0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
253c0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
253d0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
253e0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
253f0 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
25400 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
25410 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25420 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
25430 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
25440 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
25450 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
25460 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
25470 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
25480 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
25490 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
254a0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
254b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
254c0 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
254d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
254e0 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
254f0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
25500 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
25510 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
25520 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
25530 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
25540 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
25550 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
25560 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
25570 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
25580 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
25590 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
255a0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
255b0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
255c0 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
255d0 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
255e0 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
255f0 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
25600 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
25610 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
25620 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
25630 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
25640 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
25650 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
25660 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
25670 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
25680 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
25690 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
256a0 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
256b0 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
256c0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
256d0 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
256e0 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
256f0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
25700 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
25710 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
25720 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
25730 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
25740 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
25750 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
25760 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
25770 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
25780 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
25790 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
257a0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
257b0 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
257c0 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
257d0 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
257e0 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
257f0 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
25800 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
25810 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
25820 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
25830 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
25840 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
25850 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
25860 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
25870 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
25880 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
25890 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
258a0 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
258b0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
258c0 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
258d0 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
258e0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
258f0 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
25900 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
25910 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
25920 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
25930 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
25940 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
25950 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
25960 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
25970 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
25980 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
25990 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
259a0 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
259b0 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
259c0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
259d0 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
259e0 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
259f0 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
25a00 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
25a10 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
25a20 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
25a30 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
25a40 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
25a50 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
25a60 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
25a70 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
25a80 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
25a90 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
25aa0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
25ab0 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
25ac0 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
25ad0 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
25ae0 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
25af0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
25b00 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
25b10 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
25b20 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
25b30 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
25b40 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
25b50 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
25b60 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
25b70 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
25b80 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
25b90 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
25ba0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
25bb0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25bc0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
25bd0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
25be0 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
25bf0 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
25c00 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
25c10 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
25c20 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
25c30 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
25c40 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
25c50 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
25c60 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
25c70 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
25c80 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
25c90 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
25ca0 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
25cb0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
25cc0 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
25cd0 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
25ce0 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
25cf0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
25d00 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
25d10 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
25d20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
25d30 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
25d40 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
25d50 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
25d60 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
25d70 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
25d80 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25d90 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
25da0 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
25db0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
25dc0 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
25dd0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
25de0 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
25df0 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
25e00 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
25e10 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
25e20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
25e30 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
25e40 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
25e50 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
25e60 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
25e70 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
25e80 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
25e90 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
25ea0 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
25eb0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
25ec0 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
25ed0 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
25ee0 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
25ef0 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
25f00 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
25f10 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
25f20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
25f30 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
25f40 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
25f50 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
25f60 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
25f70 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
25f80 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
25f90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
25fa0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
25fb0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
25fc0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
25fd0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
25fe0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
25ff0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
26000 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
26010 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
26020 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
26030 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
26040 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
26050 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
26060 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
26070 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
26080 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
26090 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
260a0 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
260b0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
260c0 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
260d0 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
260e0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
260f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
26100 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
26110 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
26120 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
26130 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
26140 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
26150 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
26160 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
26170 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
26180 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
26190 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
261a0 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
261b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
261c0 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
261d0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
261e0 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
261f0 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
26200 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
26210 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
26220 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
26230 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
26240 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
26250 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
26260 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
26270 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
26280 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
26290 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
262a0 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
262b0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
262c0 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
262d0 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
262e0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
262f0 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
26300 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
26310 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
26320 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
26330 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
26340 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
26350 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
26360 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
26370 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
26380 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
26390 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
263a0 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
263b0 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
263c0 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
263d0 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
263e0 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
263f0 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
26400 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
26410 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
26420 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
26430 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
26440 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
26450 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
26460 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
26470 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
26480 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
26490 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
264a0 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
264b0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
264c0 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
264d0 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
264e0 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
264f0 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
26500 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
26510 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
26520 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
26530 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
26540 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
26550 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
26560 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
26570 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
26580 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
26590 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
265a0 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
265b0 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
265c0 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
265d0 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
265e0 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
265f0 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
26600 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
26610 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
26620 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
26630 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
26640 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
26650 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
26660 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
26670 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
26680 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
26690 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
266a0 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
266b0 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
266c0 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
266d0 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
266e0 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
266f0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
26700 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
26710 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
26720 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
26730 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
26740 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
26750 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
26760 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
26770 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
26780 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
26790 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
267a0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
267b0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
267c0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
267d0 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
267e0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
267f0 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
26800 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
26810 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
26820 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
26830 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
26840 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
26850 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
26860 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
26870 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26880 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
26890 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
268a0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
268b0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
268c0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
268d0 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
268e0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
268f0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
26900 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
26910 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
26920 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
26930 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
26940 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
26950 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26960 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
26970 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
26980 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
26990 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
269a0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
269b0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
269c0 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
269d0 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
269e0 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
269f0 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
26a00 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
26a10 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
26a20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
26a30 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
26a40 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
26a50 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
26a60 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
26a70 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
26a80 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
26a90 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
26aa0 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
26ab0 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
26ac0 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
26ad0 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
26ae0 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
26af0 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
26b00 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
26b10 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
26b20 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
26b30 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
26b40 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
26b50 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26b60 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
26b70 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
26b80 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26b90 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
26ba0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
26bb0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
26bc0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
26bd0 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
26be0 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
26bf0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
26c00 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
26c10 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
26c20 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
26c30 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
26c40 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
26c50 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
26c60 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
26c70 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
26c80 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
26c90 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
26ca0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
26cb0 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
26cc0 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
26cd0 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
26ce0 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
26cf0 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
26d00 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
26d10 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
26d20 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
26d30 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
26d40 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
26d50 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
26d60 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
26d70 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
26d80 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
26d90 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
26da0 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
26db0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
26dc0 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
26dd0 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
26de0 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
26df0 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
26e00 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
26e10 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
26e20 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
26e30 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
26e40 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
26e50 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
26e60 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
26e70 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
26e80 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
26e90 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
26ea0 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
26eb0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
26ec0 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
26ed0 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
26ee0 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
26ef0 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
26f00 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
26f10 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
26f20 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
26f30 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
26f40 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
26f50 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
26f60 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
26f70 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
26f80 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
26f90 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
26fa0 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
26fb0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
26fc0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
26fd0 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
26fe0 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
26ff0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
27000 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
27010 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
27020 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
27030 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
27040 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
27050 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
27060 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
27070 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
27080 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
27090 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
270a0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
270b0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
270c0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
270d0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
270e0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
270f0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
27100 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
27110 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
27120 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
27130 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
27140 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
27150 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
27160 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
27170 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
27180 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
27190 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
271a0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
271b0 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
271c0 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
271d0 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
271e0 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
271f0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
27200 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
27210 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
27220 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
27230 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
27240 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
27250 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
27260 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
27270 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
27280 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
27290 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
272a0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
272b0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
272c0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
272d0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
272e0 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
272f0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
27300 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
27310 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
27320 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
27330 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
27340 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
27350 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
27360 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
27370 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
27380 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
27390 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
273a0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
273b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
273c0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
273d0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
273e0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
273f0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
27400 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
27410 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
27420 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
27430 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
27440 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
27450 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
27460 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
27470 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
27480 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
27490 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
274a0 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
274b0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
274c0 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
274d0 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
274e0 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
274f0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
27500 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
27510 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
27520 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27530 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
27540 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
27550 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
27560 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
27570 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
27580 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
27590 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
275a0 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
275b0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
275c0 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
275d0 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
275e0 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
275f0 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
27600 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
27610 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
27620 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
27630 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
27640 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
27650 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
27660 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
27670 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
27680 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
27690 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
276a0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
276b0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
276c0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
276d0 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
276e0 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
276f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
27700 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
27710 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
27720 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
27730 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
27740 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
27750 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
27760 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
27770 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
27780 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
27790 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
277a0 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
277b0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
277c0 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
277d0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
277e0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
277f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
27800 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
27810 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
27820 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
27830 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
27840 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
27850 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
27860 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
27870 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
27880 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
27890 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
278a0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
278b0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
278c0 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
278d0 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
278e0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
278f0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
27900 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
27910 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
27920 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
27930 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
27940 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
27950 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
27960 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
27970 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
27980 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
27990 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
279a0 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
279b0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
279c0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
279d0 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
279e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
279f0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
27a00 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
27a10 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
27a20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
27a30 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
27a40 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
27a50 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
27a60 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
27a70 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
27a80 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
27a90 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
27aa0 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
27ab0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
27ac0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
27ad0 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
27ae0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
27af0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
27b00 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
27b10 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
27b20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27b30 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
27b40 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
27b50 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
27b60 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
27b70 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
27b80 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
27b90 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
27ba0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
27bb0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
27bc0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
27bd0 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
27be0 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
27bf0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
27c00 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
27c10 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
27c20 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27c30 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
27c40 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
27c50 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
27c60 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
27c70 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
27c80 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
27c90 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
27ca0 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
27cb0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
27cc0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
27cd0 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
27ce0 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
27cf0 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
27d00 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
27d10 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
27d20 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
27d30 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
27d40 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
27d50 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
27d60 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
27d70 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
27d80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
27d90 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
27da0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
27db0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
27dc0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
27dd0 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
27de0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
27df0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
27e00 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
27e10 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20  .** If the most 
27e20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
27e30 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a  was successful,.
27e40 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
27e50 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
27e60 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
27e70 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
27e80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
27e90 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
27ea0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
27eb0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
27ec0 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
27ed0 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
27ee0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
27ef0 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
27f00 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
27f10 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
27f20 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
27f30 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
27f40 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
27f50 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
27f60 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
27f70 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
27f80 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
27f90 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
27fa0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
27fb0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
27fc0 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
27fd0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
27fe0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
27ff0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
28000 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
28010 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
28020 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
28030 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
28040 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
28050 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
28060 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
28070 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
28080 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
28090 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
280a0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
280b0 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
280c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
280d0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
280e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
280f0 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
28100 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
28110 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
28120 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
28130 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
28140 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
28150 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
28160 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
28170 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
28180 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
28190 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
281a0 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
281b0 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
281c0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
281d0 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
281e0 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
281f0 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
28200 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
28210 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
28220 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
28230 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
28240 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
28250 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
28260 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
28270 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
28280 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
28290 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
282a0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
282b0 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
282c0 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
282d0 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
282e0 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
282f0 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
28300 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
28310 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
28320 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
28330 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28340 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
28350 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
28360 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
28370 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
28380 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
28390 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
283a0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
283b0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
283c0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
283d0 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
283e0 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
283f0 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
28400 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
28410 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
28420 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
28430 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
28440 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
28450 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
28460 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
28470 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
28480 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
28490 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
284a0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
284b0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
284c0 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
284d0 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
284e0 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
284f0 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
28500 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
28510 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
28520 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
28530 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
28540 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
28550 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
28560 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
28570 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
28580 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
28590 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
285a0 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
285b0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
285c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
285d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
285e0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
285f0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
28600 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
28610 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
28620 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
28630 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
28640 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
28650 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
28660 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
28670 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
28680 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
28690 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
286a0 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
286b0 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
286c0 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
286d0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
286e0 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
286f0 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
28700 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
28710 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
28720 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
28730 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
28740 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
28750 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
28760 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
28770 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
28780 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
28790 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
287a0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
287b0 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
287c0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
287d0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
287e0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
287f0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
28800 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
28810 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
28820 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
28830 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
28840 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
28850 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
28860 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
28870 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
28880 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
28890 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
288a0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
288b0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
288c0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
288d0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
288e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
288f0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
28900 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
28910 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
28920 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
28930 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
28940 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
28950 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28960 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
28970 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
28980 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
28990 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
289a0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
289b0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
289c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
289d0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
289e0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
289f0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
28a00 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
28a10 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
28a20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
28a30 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
28a40 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
28a50 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
28a60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
28a70 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
28a80 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
28a90 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
28aa0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
28ab0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
28ac0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
28ad0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
28ae0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
28af0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
28b00 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
28b10 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
28b20 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
28b30 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
28b40 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
28b50 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
28b60 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
28b70 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
28b80 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
28b90 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
28ba0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
28bb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
28bc0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
28bd0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
28be0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
28bf0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
28c00 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
28c10 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
28c20 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
28c30 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
28c40 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
28c50 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
28c60 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
28c70 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
28c80 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
28c90 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
28ca0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
28cb0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
28cc0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
28cd0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
28ce0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
28cf0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
28d00 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
28d10 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
28d20 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
28d30 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
28d40 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
28d50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28d60 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
28d70 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
28d80 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
28d90 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
28da0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
28db0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
28dc0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
28dd0 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
28de0 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
28df0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
28e00 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
28e10 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
28e20 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
28e30 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
28e40 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
28e50 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
28e60 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
28e70 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
28e80 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
28e90 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
28ea0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
28eb0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
28ec0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
28ed0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
28ee0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
28ef0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
28f00 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
28f10 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
28f20 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
28f30 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
28f40 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
28f50 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
28f60 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
28f70 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
28f80 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
28f90 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
28fa0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
28fb0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
28fc0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
28fd0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
28fe0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
28ff0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
29000 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
29010 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
29020 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
29030 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
29040 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
29050 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
29060 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
29070 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
29080 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
29090 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
290a0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
290b0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
290c0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
290d0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
290e0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
290f0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
29100 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
29110 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
29120 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
29130 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
29140 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
29150 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
29160 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
29170 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
29180 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
29190 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
291a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
291b0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
291c0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
291d0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
291e0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
291f0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
29200 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
29210 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
29220 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
29230 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
29240 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
29250 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
29260 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
29270 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
29280 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
29290 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
292a0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
292b0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
292c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
292d0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
292e0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
292f0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
29300 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
29310 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
29320 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29330 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
29340 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29350 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
29360 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
29370 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
29380 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
29390 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
293a0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
293b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
293c0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
293d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
293e0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
293f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
29400 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
29410 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29420 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
29430 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29440 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
29450 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29460 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
29470 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
29480 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
29490 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
294a0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
294b0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
294c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
294d0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
294e0 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
294f0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
29500 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
29510 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29520 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
29530 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29540 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
29550 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29560 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
29570 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
29580 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
29590 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
295a0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
295b0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
295c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
295d0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
295e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
295f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29600 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
29610 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
29620 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
29630 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29640 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
29650 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29660 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
29670 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29680 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
29690 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
296a0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
296b0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
296c0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
296d0 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b  statement.  If [
296e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
296f0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20  v2()] or.** the 
29700 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73  equivalent tries
29710 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61   to allocate spa
29720 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e  ce for more than
29730 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64   this many opcod
29740 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c  es.** in a singl
29750 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
29760 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f  ment, an SQLITE_
29770 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72  NOMEM error is r
29780 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
29790 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
297a0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
297b0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
297c0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
297d0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
297e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
297f0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
29800 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
29810 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29820 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
29830 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
29840 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
29850 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
29860 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29870 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
29880 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
29890 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
298a0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
298b0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
298c0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
298d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
298e0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
298f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29900 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
29910 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
29920 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
29930 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
29940 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
29950 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29960 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
29970 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
29980 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29990 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
299a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
299b0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
299c0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
299d0 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
299e0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
299f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29a00 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
29a10 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
29a20 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
29a30 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
29a40 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
29a50 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
29a60 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
29a70 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29a80 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
29a90 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
29aa0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
29ab0 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
29ac0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29ad0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
29ae0 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
29af0 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
29b00 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
29b10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
29b20 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
29b30 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
29b40 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29b50 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
29b60 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
29b70 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29b80 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
29b90 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
29ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29bb0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
29bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
29bd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29be0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
29bf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
29c00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29c10 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
29c20 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
29c30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29c40 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
29c50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29c60 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
29c70 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
29c80 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
29c90 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
29ca0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
29cb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29cc0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
29cd0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
29ce0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
29cf0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
29d00 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
29d10 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
29d20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
29d30 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
29d40 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
29d50 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
29d60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
29d70 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
29d80 20 20 20 20 20 31 31 0a 0a 0a 2f 2a 0a 2a 2a 20       11.../*.** 
29d90 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
29da0 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
29db0 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
29dc0 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
29dd0 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45   compiler}.** ME
29de0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
29df0 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
29e00 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
29e10 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
29e20 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
29e30 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
29e40 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
29e50 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
29e60 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
29e70 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
29e80 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
29e90 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
29ea0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
29eb0 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
29ec0 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
29ed0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
29ee0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
29ef0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
29f00 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
29f10 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
29f20 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
29f30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
29f40 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
29f50 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
29f60 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
29f70 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
29f80 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
29f90 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
29fa0 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
29fb0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
29fc0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
29fd0 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
29fe0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
29ff0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
2a000 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
2a010 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a020 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
2a030 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
2a040 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
2a050 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
2a060 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67   argument is neg
2a070 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c  ative, then zSql
2a080 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
2a090 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
2a0a0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
2a0b0 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69   nByte is positi
2a0c0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
2a0d0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2a0e0 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
2a0f0 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65  zSql.  ^If nByte
2a100 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e   is zero, then n
2a110 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  o prepared.** st
2a120 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72  atement is gener
2a130 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ated..** If the 
2a140 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61  caller knows tha
2a150 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
2a160 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
2a170 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a  minated, then.**
2a180 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
2a190 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  l performance ad
2a1a0 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69  vantage to passi
2a1b0 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
2a1c0 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
2a1d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2a1e0 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
2a1f0 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
2a200 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
2a210 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e   nul-terminator.
2a220 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
2a230 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
2a240 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
2a250 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
2a260 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
2a270 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
2a280 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
2a290 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2a2a0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2a2b0 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
2a2c0 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
2a2d0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
2a2e0 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
2a2f0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
2a300 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
2a310 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
2a320 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
2a330 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
2a340 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
2a350 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2a360 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
2a370 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
2a380 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
2a390 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
2a3a0 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
2a3b0 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
2a3c0 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
2a3d0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
2a3e0 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
2a3f0 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
2a400 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
2a410 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
2a420 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
2a430 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
2a440 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
2a450 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
2a460 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
2a470 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
2a480 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
2a490 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2a4a0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
2a4b0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
2a4c0 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
2a4d0 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
2a4e0 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
2a4f0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2a500 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
2a510 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2a520 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
2a530 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
2a540 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2a550 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
2a560 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a570 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
2a580 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
2a590 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
2a5a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
2a5b0 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
2a5c0 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
2a5d0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2a5e0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
2a5f0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2a600 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
2a610 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
2a620 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
2a630 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2a640 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
2a650 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
2a660 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
2a670 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2a680 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
2a690 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2a6a0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2a6b0 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
2a6c0 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
2a6d0 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
2a6e0 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
2a6f0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
2a700 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
2a710 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
2a720 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
2a730 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
2a740 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
2a750 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
2a760 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
2a770 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
2a780 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2a790 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
2a7a0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
2a7b0 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
2a7c0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
2a7d0 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73  run it again. As
2a7e0 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45   many as [SQLITE
2a7f0 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52  _MAX_SCHEMA_RETR
2a800 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69  Y].** retries wi
2a810 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20  ll occur before 
2a820 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67  sqlite3_step() g
2a830 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75  ives up and retu
2a840 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  rns an error..**
2a850 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2a860 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
2a870 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
2a880 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2a890 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
2a8a0 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
2a8b0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
2a8c0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2a8d0 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
2a8e0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
2a8f0 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
2a900 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
2a910 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
2a920 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
2a930 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
2a940 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
2a950 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
2a960 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
2a970 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
2a980 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
2a990 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
2a9a0 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
2a9b0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
2a9c0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
2a9d0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
2a9e0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
2a9f0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
2aa00 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
2aa10 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
2aa20 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
2aa30 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2aa40 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2aa50 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
2aa60 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
2aa70 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
2aa80 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
2aa90 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
2aaa0 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
2aab0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2aac0 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
2aad0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
2aae0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
2aaf0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2ab00 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
2ab10 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
2ab20 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
2ab30 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
2ab40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ab50 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
2ab60 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
2ab70 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
2ab80 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
2ab90 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
2aba0 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
2abb0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2abc0 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
2abd0 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
2abe0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2abf0 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
2ac00 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
2ac10 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
2ac20 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
2ac30 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
2ac40 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
2ac50 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
2ac60 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
2ac70 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
2ac80 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
2ac90 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
2aca0 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
2acb0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
2acc0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c   enabled..** </l
2acd0 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
2ace0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2acf0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
2ad00 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2ad10 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2ad20 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2ad30 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2ad40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2ad50 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2ad60 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2ad70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2ad80 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2ad90 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2ada0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2adb0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2adc0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2add0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2ade0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2adf0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2ae00 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2ae10 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2ae20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2ae30 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
2ae40 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2ae50 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2ae60 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2ae70 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2ae80 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2ae90 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2aea0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2aeb0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2aec0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2aed0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2aee0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2aef0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2af00 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2af10 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2af20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2af30 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2af40 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2af50 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2af60 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2af70 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
2af80 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2af90 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2afa0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2afb0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2afc0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2afd0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2afe0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2aff0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2b000 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2b010 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2b020 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2b030 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2b040 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2b050 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2b060 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2b070 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2b080 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2b090 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2b0a0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2b0b0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2b0c0 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
2b0d0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2b0e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2b0f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2b100 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2b110 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2b120 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2b130 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2b140 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2b150 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2b160 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2b170 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2b180 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2b190 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2b1a0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2b1b0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2b1c0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2b1d0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2b1e0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2b1f0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2b200 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2b210 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2b220 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2b230 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2b240 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  The sqlite3_sql(
2b250 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2b260 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2b270 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  o a copy of the 
2b280 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78  UTF-8.** SQL tex
2b290 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2b2a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b2b0 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73  ment] P if P was
2b2c0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 65  .** created by e
2b2d0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2b2e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2b2f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b300 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  16_v2()]..** ^Th
2b310 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2b320 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  ed_sql(P) interf
2b330 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2b340 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38  inter to a UTF-8
2b350 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
2b360 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65  ining the SQL te
2b370 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73  xt of prepared s
2b380 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a  tatement P with.
2b390 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  ** [bound parame
2b3a0 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a  ters] expanded..
2b3b0 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2b3c0 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72  ple, if a prepar
2b3d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2b3e0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
2b3f0 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53  e SQL.** text "S
2b400 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2b410 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65   and if paramete
2b420 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20  r $abc is bound 
2b430 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a  to integer 2345.
2b440 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72  ** and parameter
2b450 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64   :xyz is unbound
2b460 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  , then sqlite3_s
2b470 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ql() will return
2b480 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
2b490 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54   string, "SELECT
2b4a0 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20   $abc,:xyz" but 
2b4b0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2b4c0 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72  _sql().** will r
2b4d0 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33  eturn "SELECT 23
2b4e0 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a  45,NULL".)^.**.*
2b4f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2b500 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e  xpanded_sql() in
2b510 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b520 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
2b530 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  ient memory.** i
2b540 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68  s available to h
2b550 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20  old the result, 
2b560 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74  or if the result
2b570 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2b580 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d  e.** the maximum
2b590 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64   string length d
2b5a0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
2b5b0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c   [SQLITE_LIMIT_L
2b5c0 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ENGTH]..**.** ^T
2b5d0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
2b5e0 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
2b5f0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2b600 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65   limits the size
2b610 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72   of.** bound par
2b620 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e  ameter expansion
2b630 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  s.  ^The [SQLITE
2b640 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d  _OMIT_TRACE] com
2b650 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
2b660 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74  ion causes sqlit
2b670 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2b680 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75  ) to always retu
2b690 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  rn NULL..**.** ^
2b6a0 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2b6b0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  ned by sqlite3_s
2b6c0 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64  ql(P) is managed
2b6d0 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69   by SQLite and i
2b6e0 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2b6f0 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68  ly freed when th
2b700 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2b710 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2b720 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2b730 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2b740 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2b750 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2b760 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2b770 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2b780 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2b790 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2b7a0 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2b7b0 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2b7c0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2b7d0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f  3_free()]..*/.co
2b7e0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2b7f0 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
2b800 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72  mt *pStmt);.char
2b810 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   *sqlite3_expand
2b820 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2b830 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2b840 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2b850 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
2b860 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
2b870 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
2b880 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2b890 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2b8a0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2b8b0 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
2b8c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2b8d0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2b8e0 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
2b8f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2b900 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
2b910 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
2b920 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
2b930 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2b940 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
2b950 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
2b960 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b970 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
2b980 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
2b990 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
2b9a0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2b9b0 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
2b9c0 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
2b9d0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2b9e0 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
2b9f0 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
2ba00 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
2ba10 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
2ba20 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
2ba30 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
2ba40 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
2ba50 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
2ba60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2ba70 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
2ba80 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
2ba90 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
2baa0 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
2bab0 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
2bac0 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
2bad0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
2bae0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
2baf0 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
2bb00 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
2bb10 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2bb20 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
2bb30 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
2bb40 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2bb50 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
2bb60 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
2bb70 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
2bb80 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
2bb90 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
2bba0 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
2bbb0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
2bbc0 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
2bbd0 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
2bbe0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2bbf0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2bc00 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
2bc10 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
2bc20 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
2bc30 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
2bc40 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2bc50 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
2bc60 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
2bc70 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
2bc80 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
2bc90 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
2bca0 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
2bcb0 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
2bcc0 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
2bcd0 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
2bce0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2bcf0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2bd00 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
2bd10 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
2bd20 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
2bd30 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
2bd40 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
2bd50 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
2bd60 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
2bd70 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
2bd80 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2bd90 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
2bda0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  k..** ^The sqlit
2bdb0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2bdc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2bdd0 75 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42  urns true for [B
2bde0 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b  EGIN] since.** [
2bdf0 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65  BEGIN] merely se
2be00 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67  ts internal flag
2be10 73 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49  s, but the [BEGI
2be20 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54  N|BEGIN IMMEDIAT
2be30 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e  E] and.** [BEGIN
2be40 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45  |BEGIN EXCLUSIVE
2be50 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f  ] commands do to
2be60 75 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  uch the database
2be70 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74   and so.** sqlit
2be80 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2be90 28 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  () returns false
2bea0 20 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61   for those comma
2beb0 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
2bec0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2bed0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
2bee0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2bef0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2bf00 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
2bf10 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
2bf20 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54  een Reset.** MET
2bf30 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2bf40 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2bf50 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2bf60 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2bf70 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2bf80 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
2bf90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bfa0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
2bfb0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
2bfc0 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
2bfd0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2bfe0 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20  but has neither 
2bff0 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
2c000 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  n (returned.** [
2c010 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f  SQLITE_DONE] fro
2c020 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  m [sqlite3_step(
2c030 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e  S)]) nor.** been
2c040 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
2c050 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
2c060 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
2c070 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
2c080 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2c090 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
2c0a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
2c0b0 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
2c0c0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
2c0d0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
2c0e0 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
2c0f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c100 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
2c110 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2c120 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2c130 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
2c140 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
2c150 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
2c160 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
2c170 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
2c180 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
2c190 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
2c1a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c1b0 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
2c1c0 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
2c1d0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
2c1e0 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
2c1f0 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
2c200 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
2c210 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
2c220 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
2c230 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
2c240 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
2c250 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
2c260 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
2c270 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
2c280 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
2c290 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
2c2a0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2c2b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
2c2c0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
2c2d0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
2c2e0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
2c2f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c300 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
2c310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
2c320 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
2c330 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
2c340 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
2c350 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
2c360 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
2c370 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
2c380 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
2c390 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2c3a0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
2c3b0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
2c3c0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
2c3d0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
2c3e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
2c3f0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
2c400 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
2c410 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
2c420 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
2c430 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
2c440 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2c450 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
2c460 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
2c470 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
2c480 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
2c490 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
2c4a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c4b0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
2c4c0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
2c4d0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
2c4e0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
2c4f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c500 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
2c510 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
2c520 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
2c530 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
2c540 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
2c550 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
2c560 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
2c570 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c580 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
2c590 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20  e3_value_dup()] 
2c5a0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2c5b0 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75   used to constru
2c5c0 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f  ct a new .** pro
2c5d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c5e0 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70  alue from an unp
2c5f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c600 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
2c610 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
2c620 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
2c630 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
2c640 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
2c650 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
2c660 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
2c670 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2c680 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
2c690 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c6a0 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
2c6b0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
2c6c0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2c6d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c6e0 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
2c6f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
2c700 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
2c710 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
2c720 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
2c730 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
2c740 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2c750 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
2c760 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
2c770 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
2c780 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
2c790 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
2c7a0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
2c7b0 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
2c7c0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2c7d0 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
2c7e0 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
2c7f0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2c800 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2c810 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2c820 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
2c830 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
2c840 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
2c850 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
2c860 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
2c870 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
2c880 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
2c890 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
2c8a0 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
2c8b0 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
2c8c0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2c8d0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2c8e0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2c8f0 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
2c900 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
2c910 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
2c920 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c930 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
2c940 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
2c950 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
2c960 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
2c970 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
2c980 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2c990 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
2c9a0 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
2c9b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2c9c0 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
2c9d0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2c9e0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2c9f0 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
2ca00 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
2ca10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2ca20 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
2ca30 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
2ca40 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2ca50 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2ca60 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2ca70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
2ca80 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
2ca90 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
2caa0 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
2cab0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
2cac0 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
2cad0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2cae0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
2caf0 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
2cb00 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
2cb10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2cb20 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
2cb30 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
2cb40 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
2cb50 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
2cb60 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
2cb70 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
2cb80 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
2cb90 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
2cba0 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
2cbb0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2cbc0 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
2cbd0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2cbe0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
2cbf0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2cc00 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
2cc10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2cc20 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2cc30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2cc40 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
2cc50 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
2cc60 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
2cc70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2cc80 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
2cc90 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
2cca0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2ccb0 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
2ccc0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
2ccd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
2cce0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
2ccf0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
2cd00 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
2cd10 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
2cd20 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
2cd30 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2cd40 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2cd50 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2cd60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cd70 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
2cd80 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
2cd90 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
2cda0 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
2cdb0 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
2cdc0 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
2cdd0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
2cde0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
2cdf0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
2ce00 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
2ce10 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
2ce20 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2ce30 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2ce40 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
2ce50 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
2ce60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
2ce70 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
2ce80 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
2ce90 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
2cea0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
2ceb0 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
2cec0 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
2ced0 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
2cee0 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
2cef0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
2cf00 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
2cf10 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
2cf20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
2cf30 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
2cf40 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
2cf50 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
2cf60 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
2cf70 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
2cf80 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
2cf90 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
2cfa0 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
2cfb0 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
2cfc0 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
2cfd0 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
2cfe0 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
2cff0 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
2d000 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
2d010 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
2d020 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
2d030 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2d040 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
2d050 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2d060 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2d070 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2d080 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
2d090 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
2d0a0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2d0b0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
2d0c0 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
2d0d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d0e0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
2d0f0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
2d100 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2d110 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2d120 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
2d130 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
2d140 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
2d150 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
2d160 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
2d170 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
2d180 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
2d190 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
2d1a0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
2d1b0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2d1c0 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
2d1d0 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
2d1e0 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
2d1f0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
2d200 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
2d210 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
2d220 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
2d230 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
2d240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2d250 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2d260 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
2d270 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
2d280 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
2d290 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
2d2a0 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
2d2b0 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
2d2c0 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
2d2d0 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
2d2e0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
2d2f0 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
2d300 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2d310 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
2d320 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
2d330 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2d340 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
2d350 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
2d360 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
2d370 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
2d380 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2d390 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2d3a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2d3b0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20  _text16().** or 
2d3c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2d3d0 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  b() is a NULL po
2d3e0 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66  inter then the f
2d3f0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a  ourth parameter.
2d400 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e  ** is ignored an
2d410 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74  d the end result
2d420 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
2d430 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2d440 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  l()..**.** ^(In 
2d450 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
2d460 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
2d470 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
2d480 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2d490 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2d4a0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2d4b0 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
2d4c0 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
2d4d0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
2d4e0 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
2d4f0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
2d500 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2d510 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
2d520 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2d530 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2d540 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2d550 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d560 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74  16().** is negat
2d570 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65  ive, then the le
2d580 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
2d590 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
2d5a0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
2d5b0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2d5c0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2d5d0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
2d5e0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2d5f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
2d600 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2d610 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f  n.** the behavio
2d620 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2d630 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61  ** If a non-nega
2d640 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61  tive fourth para
2d650 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65  meter is provide
2d660 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  d to sqlite3_bin
2d670 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73  d_text().** or s
2d680 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d690 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  16() or sqlite3_
2d6a0 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68  bind_text64() th
2d6b0 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d  en.** that param
2d6c0 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
2d6d0 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
2d6e0 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
2d6f0 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
2d700 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
2d710 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
2d720 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
2d730 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
2d740 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
2d750 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
2d760 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
2d770 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
2d780 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
2d790 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
2d7a0 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
2d7b0 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
2d7c0 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
2d7d0 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
2d7e0 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
2d7f0 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
2d800 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
2d810 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2d820 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
2d830 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42  rgument to the B
2d840 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62  LOB and string b
2d850 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65  inding interface
2d860 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75  s.** is a destru
2d870 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
2d880 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2d890 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
2d8a0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
2d8b0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
2d8c0 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
2d8d0 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
2d8e0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2d8f0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2d900 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
2d910 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69   to bind API fai
2d920 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ls..** ^If the f
2d930 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
2d940 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
2d950 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
2d960 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
2d970 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
2d980 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
2d990 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
2d9a0 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
2d9b0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
2d9c0 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
2d9d0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
2d9e0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
2d9f0 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
2da00 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
2da10 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
2da20 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2da30 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
2da40 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
2da50 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
2da60 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2da70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
2da80 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20  *.** ^The sixth 
2da90 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2daa0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2dab0 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
2dac0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2dad0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2dae0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2daf0 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
2db00 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73  UTF16LE].** to s
2db10 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64  pecify the encod
2db20 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20  ing of the text 
2db30 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
2db40 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74  ameter.  If.** t
2db50 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2db60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2db70 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f  d_text64() is no
2db80 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
2db90 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73  allowed values s
2dba0 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69  hown above, or i
2dbb0 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  f the text encod
2dbc0 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
2dbd0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63  .** from the enc
2dbe0 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20  oding specified 
2dbf0 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72  by the sixth par
2dc00 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
2dc10 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
2dc20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2dc30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2dc40 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
2dc50 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
2dc60 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
2dc70 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
2dc80 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
2dc90 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
2dca0 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
2dcb0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
2dcc0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
2dcd0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
2dce0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
2dcf0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
2dd00 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
2dd10 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
2dd20 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
2dd30 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
2dd40 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
2dd50 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
2dd60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2dd70 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
2dd80 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
2dd90 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
2dda0 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
2ddb0 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
2ddc0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
2ddd0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
2dde0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
2ddf0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2de00 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
2de10 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
2de20 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
2de30 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2de40 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
2de50 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
2de60 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
2de70 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
2de80 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
2de90 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
2dea0 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
2deb0 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
2dec0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
2ded0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
2dee0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
2def0 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
2df00 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
2df10 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
2df20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2df30 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
2df40 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
2df50 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2df60 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2df70 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
2df80 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
2df90 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
2dfa0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2dfb0 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
2dfc0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
2dfd0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
2dfe0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
2dff0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2e000 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
2e010 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2e020 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
2e030 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
2e040 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
2e050 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
2e060 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69  QLITE_TOOBIG] mi
2e070 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2e080 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  if the size of a
2e090 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a   string or BLOB.
2e0a0 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74  ** exceeds limit
2e0b0 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71  s imposed by [sq
2e0c0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2e0d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2e0e0 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  H]) or.** [SQLIT
2e0f0 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  E_MAX_LENGTH]..*
2e100 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
2e110 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2e120 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
2e130 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
2e140 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
2e150 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
2e160 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
2e170 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
2e180 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2e190 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e1a0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
2e1b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e1c0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2e1d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2e1e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2e1f0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2e200 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
2e210 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e220 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2e230 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
2e240 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2e250 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73  e3_bind_blob64(s
2e260 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e270 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2e280 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
2e290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e2a0 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2e2b0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2e2c0 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
2e2d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e2e0 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
2e2f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2e300 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2e310 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
2e320 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2e330 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2e340 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
2e350 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
2e360 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
2e370 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e380 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2e390 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
2e3a0 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74  _stmt*,int,const
2e3b0 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28   char*,int,void(
2e3c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2e3d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2e3e0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2e3f0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2e400 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2e410 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2e420 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2e430 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2e440 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
2e450 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
2e460 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2e470 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2e480 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
2e490 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
2e4a0 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ing);.int sqlite
2e4b0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
2e4c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2e4d0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
2e4e0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2e4f0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2e500 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2e510 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e   int, int n);.in
2e520 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2e530 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  eroblob64(sqlite
2e540 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2e550 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a  lite3_uint64);..
2e560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e570 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
2e580 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48  rameters.** METH
2e590 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e5a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2e5b0 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
2e5c0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
2e5d0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
2e5e0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
2e5f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e600 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
2e610 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
2e620 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
2e630 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
2e640 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
2e650 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
2e660 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
2e670 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
2e680 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
2e690 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
2e6a0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
2e6b0 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
2e6c0 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
2e6d0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2e6e0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
2e6f0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2e700 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
2e710 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
2e720 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
2e730 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
2e740 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
2e750 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
2e760 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
2e770 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
2e780 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2e790 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
2e7a0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
2e7b0 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
2e7c0 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
2e7d0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2e7e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2e7f0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2e800 5b 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 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2e820 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2e830 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e840 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
2e850 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2e860 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
2e870 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2e880 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2e890 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
2e8a0 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f  rameter.** METHO
2e8b0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2e8c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e8d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e8e0 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
2e8f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
2e900 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2e910 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
2e920 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
2e930 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e940 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
2e950 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2e960 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
2e970 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2e980 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
2e990 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
2e9a0 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
2e9b0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2e9c0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2e9d0 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
2e9e0 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
2e9f0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
2ea00 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
2ea10 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
2ea20 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
2ea30 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
2ea40 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
2ea50 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
2ea60 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
2ea70 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
2ea80 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
2ea90 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
2eaa0 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
2eab0 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
2eac0 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
2ead0 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
2eae0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
2eaf0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
2eb00 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
2eb10 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
2eb20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
2eb30 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
2eb40 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
2eb50 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
2eb60 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
2eb70 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2eb80 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
2eb90 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
2eba0 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
2ebb0 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
2ebc0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
2ebd0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
2ebe0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
2ebf0 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
2ec00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ec10 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2ec20 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2ec30 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2ec40 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2ec50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ec60 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2ec70 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2ec80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ec90 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
2eca0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2ecb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ecc0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2ecd0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
2ece0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
2ecf0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
2ed00 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
2ed10 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  me.** METHOD: sq
2ed20 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2ed30 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
2ed40 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
2ed50 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
2ed60 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
2ed70 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
2ed80 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
2ed90 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
2eda0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
2edb0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2edc0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2edd0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
2ede0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
2edf0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
2ee00 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
2ee10 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
2ee20 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
2ee30 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
2ee40 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
2ee50 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
2ee60 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
2ee70 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
2ee80 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
2ee90 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2eea0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2eeb0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2eec0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2eed0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [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 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2ef00 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2ef10 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2ef20 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  e()]..*/.int sql
2ef30 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ef40 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
2ef50 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
2ef60 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
2ef70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2ef80 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
2ef90 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
2efa0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48  tatement.** METH
2efb0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2efc0 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
2efd0 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
2efe0 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
2eff0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
2f000 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
2f010 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2f020 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
2f030 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
2f040 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2f050 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
2f060 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
2f070 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
2f080 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
2f090 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2f0a0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2f0b0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2f0c0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2f0d0 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
2f0e0 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2f0f0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2f100 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2f110 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2f120 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2f130 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
2f140 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
2f150 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2f160 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
2f170 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74   returns 0, that
2f180 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b   means the .** [
2f190 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f1a0 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64  nt] returns no d
2f1b0 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
2f1c0 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
2f1d0 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74  * ^However, just
2f1e0 20 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f   because this ro
2f1f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
2f200 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20  positive number 
2f210 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e  does not.** mean
2f220 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72   that one or mor
2f230 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77  e rows of data w
2f240 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
2f250 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74    ^A SELECT stat
2f260 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ement.** will al
2f270 77 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69  ways have a posi
2f280 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  tive sqlite3_col
2f290 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20  umn_count() but 
2f2a0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2f2b0 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2f2c0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
2f2d0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65   the table conte
2f2e0 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74  nt, it might ret
2f2f0 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a  urn no rows..**.
2f300 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2f310 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2f320 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
2f330 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2f340 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2f350 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2f360 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
2f370 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
2f380 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
2f390 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2f3a0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2f3b0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
2f3c0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
2f3d0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
2f3e0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
2f3f0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2f400 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2f410 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2f420 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
2f430 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2f440 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2f450 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2f460 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2f470 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2f480 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
2f490 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2f4a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2f4b0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
2f4c0 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
2f4d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2f4e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f4f0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
2f500 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
2f510 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2f520 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2f530 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2f540 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
2f550 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
2f560 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
2f570 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
2f580 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
2f590 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
2f5a0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
2f5b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f5c0 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
2f5d0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2f5e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2f5f0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2f600 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2f610 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2f620 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2f630 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2f640 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2f650 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2f660 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
2f670 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
2f680 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2f690 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
2f6a0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2f6b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
2f6c0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
2f6d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
2f6e0 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
2f6f0 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
2f700 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
2f710 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
2f720 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
2f730 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
2f740 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
2f750 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2f760 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2f770 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
2f780 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
2f790 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2f7a0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
2f7b0 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
2f7c0 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
2f7d0 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
2f7e0 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
2f7f0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
2f800 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2f810 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
2f820 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
2f830 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
2f840 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2f850 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
2f860 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2f870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2f880 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f890 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
2f8a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2f8b0 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
2f8c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2f8d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f8e0 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
2f8f0 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
2f900 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
2f910 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f920 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2f930 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
2f940 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
2f950 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
2f960 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
2f970 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
2f980 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
2f990 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
2f9a0 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
2f9b0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2f9c0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
2f9d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
2f9e0 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
2f9f0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
2fa00 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
2fa10 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2fa20 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
2fa30 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
2fa40 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
2fa50 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
2fa60 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
2fa70 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2fa80 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
2fa90 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
2faa0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2fab0 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
2fac0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2fad0 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
2fae0 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
2faf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fb00 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
2fb10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2fb20 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2fb30 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2fb40 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2fb50 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2fb60 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2fb70 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2fb80 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2fb90 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2fba0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
2fbb0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2fbc0 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
2fbd0 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
2fbe0 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
2fbf0 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
2fc00 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
2fc10 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
2fc20 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
2fc30 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
2fc40 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
2fc50 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2fc60 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
2fc70 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
2fc80 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2fc90 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
2fca0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2fcb0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2fcc0 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
2fcd0 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
2fce0 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
2fcf0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
2fd00 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
2fd10 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2fd20 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
2fd30 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
2fd40 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
2fd50 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
2fd60 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2fd70 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
2fd80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2fd90 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
2fda0 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
2fdb0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
2fdc0 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
2fdd0 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
2fde0 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
2fdf0 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
2fe00 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
2fe10 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
2fe20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2fe30 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
2fe40 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
2fe50 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
2fe60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
2fe70 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
2fe80 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
2fe90 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
2fea0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
2feb0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
2fec0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
2fed0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
2fee0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
2fef0 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
2ff00 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
2ff10 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2ff20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
2ff30 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
2ff40 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
2ff50 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
2ff60 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
2ff70 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
2ff80 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
2ff90 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
2ffa0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
2ffb0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
2ffc0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2ffd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2ffe0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2fff0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
30000 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
30010 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
30020 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
30030 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
30040 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
30050 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
30060 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
30070 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
30080 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
30090 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
300a0 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
300b0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
300c0 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
300d0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
300e0 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
300f0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
30100 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
30110 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
30120 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
30130 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
30140 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
30150 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
30160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
30170 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
30180 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
30190 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
301a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
301b0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
301c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
301d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
301e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
301f0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
30200 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
30210 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
30220 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
30230 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
30240 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
30250 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30260 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
30270 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
30280 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
30290 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
302a0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
302b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
302c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
302d0 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
302e0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
302f0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
30300 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30310 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
30320 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
30330 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
30340 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
30350 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
30360 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
30370 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
30380 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
30390 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
303a0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
303b0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
303c0 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
303d0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
303e0 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
303f0 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
30400 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
30410 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
30420 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
30430 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
30440 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
30450 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
30460 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
30470 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
30480 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
30490 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
304a0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
304b0 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
304c0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
304d0 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
304e0 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
304f0 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
30500 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
30510 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
30520 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
30530 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
30540 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
30550 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
30560 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
30570 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
30580 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
30590 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
305a0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
305b0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
305c0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
305d0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
305e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
305f0 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
30600 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
30610 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
30620 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
30630 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
30640 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
30650 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
30660 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
30670 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
30680 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
30690 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
306a0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
306b0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
306c0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
306d0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
306e0 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
306f0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
30700 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
30710 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
30720 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
30730 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
30740 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
30750 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
30760 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
30770 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30780 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
30790 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
307a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
307b0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
307c0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
307d0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
307e0 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
307f0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
30800 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
30810 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30820 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
30830 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
30840 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
30850 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
30860 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
30870 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
30880 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
30890 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
308a0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
308b0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
308c0 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
308d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
308e0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
308f0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
30900 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
30910 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
30920 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
30930 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
30940 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
30950 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
30960 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
30970 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
30980 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
30990 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
309a0 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
309b0 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
309c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
309d0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
309e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
309f0 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
30a00 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
30a10 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
30a20 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
30a30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30a40 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
30a50 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
30a60 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
30a70 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
30a80 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
30a90 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
30aa0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
30ab0 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
30ac0 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
30ad0 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
30ae0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
30af0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
30b00 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
30b10 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
30b20 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
30b30 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
30b40 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
30b50 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
30b60 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
30b70 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
30b80 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
30b90 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
30ba0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
30bb0 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
30bc0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
30bd0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
30be0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
30bf0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
30c00 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
30c10 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
30c20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
30c30 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
30c40 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
30c50 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
30c60 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
30c70 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
30c80 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
30c90 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
30ca0 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
30cb0 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
30cc0 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
30cd0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
30ce0 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
30cf0 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a  urs within an.**
30d00 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
30d10 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
30d20 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
30d30 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
30d40 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
30d50 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
30d60 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
30d70 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
30d80 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
30d90 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
30da0 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
30db0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
30dc0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
30dd0 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
30de0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
30df0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
30e00 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
30e10 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
30e20 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
30e30 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
30e40 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
30e50 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
30e60 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
30e70 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
30e80 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
30e90 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
30ea0 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
30eb0 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
30ec0 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
30ed0 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
30ee0 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
30ef0 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
30f00 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
30f10 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
30f20 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
30f30 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
30f40 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
30f50 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
30f60 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
30f70 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
30f80 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
30f90 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
30fa0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
30fb0 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
30fc0 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
30fd0 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
30fe0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
30ff0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
31000 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
31010 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
31020 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
31030 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
31040 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
31050 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
31060 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
31070 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
31080 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
31090 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
310a0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
310b0 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
310c0 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
310d0 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
310e0 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
310f0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
31100 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
31110 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
31120 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31130 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
31140 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
31150 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
31160 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
31170 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
31180 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
31190 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
311a0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
311b0 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
311c0 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
311d0 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
311e0 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
311f0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
31200 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
31210 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
31220 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
31230 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
31240 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
31250 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
31260 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
31270 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
31280 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
31290 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
312a0 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
312b0 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
312c0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
312d0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
312e0 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
312f0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
31300 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
31310 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
31320 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
31330 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
31340 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
31350 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61  g 3.6.23.1, a ca
31360 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
31370 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72  3_reset()] was r
31380 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71  equired after sq
31390 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
313a0 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a  urned anything.*
313b0 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  * other than [SQ
313c0 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65  LITE_ROW] before
313d0 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
313e0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
313f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
31400 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73    Failure to res
31410 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
31420 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
31430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
31440 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75  et()] would resu
31450 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
31460 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
31470 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
31480 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
31490 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e  er [version 3.6.
314a0 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33  23.1] ([dateof:3
314b0 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c  .6.23.1],.** sql
314c0 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
314d0 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
314e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
314f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
31500 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
31510 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
31520 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
31530 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
31540 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
31550 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
31560 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
31570 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
31580 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
31590 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
315a0 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
315b0 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
315c0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
315d0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
315e0 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
315f0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
31600 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
31610 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
31620 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
31630 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
31640 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
31650 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
31660 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
31670 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
31680 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
31690 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
316a0 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
316b0 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
316c0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
316d0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
316e0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
316f0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
31700 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
31710 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
31720 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
31730 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
31740 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
31750 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
31760 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
31770 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
31780 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
31790 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
317a0 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
317b0 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
317c0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
317d0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
317e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
317f0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
31800 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
31810 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
31820 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
31830 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
31840 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
31850 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
31860 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
31870 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
31880 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
31890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
318a0 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
318b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
318c0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
318d0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
318e0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
318f0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
31900 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
31910 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
31920 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
31930 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
31940 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
31950 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
31960 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
31970 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
31980 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45  result set.** ME
31990 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
319a0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
319b0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
319c0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
319d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
319e0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
319f0 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
31a00 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
31a10 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
31a20 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
31a30 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
31a40 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
31a50 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
31a60 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
31a70 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
31a80 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
31a90 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
31aa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
31ab0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
31ac0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
31ad0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
31ae0 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
31af0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
31b00 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
31b10 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
31b20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
31b30 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
31b40 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31b50 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
31b60 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
31b70 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
31b80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
31b90 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
31ba0 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
31bb0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
31bc0 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
31bd0 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
31be0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
31bf0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
31c00 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
31c10 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
31c20 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
31c30 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
31c40 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
31c50 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
31c60 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
31c70 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
31c80 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
31c90 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
31ca0 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
31cb0 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
31cc0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
31cd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
31ce0 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
31cf0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
31d00 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
31d10 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
31d20 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
31d30 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
31d40 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
31d50 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
31d60 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
31d70 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
31d80 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
31d90 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
31da0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
31db0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
31dc0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
31dd0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
31de0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
31df0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
31e00 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
31e10 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
31e20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
31e30 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
31e40 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
31e50 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
31e60 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
31e70 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
31e80 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
31e90 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
31ea0 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
31eb0 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
31ec0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
31ed0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
31ee0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
31ef0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
31f00 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
31f10 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
31f20 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
31f30 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
31f40 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
31f50 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
31f60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31f70 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
31f80 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
31f90 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
31fa0 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
31fb0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
31fc0 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
31fd0 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
31fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
31ff0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
32000 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
32010 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
32020 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
32030 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
32040 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
32050 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
32060 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
32070 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
32080 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
32090 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
320a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
320b0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
320c0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
320d0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
320e0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
320f0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
32100 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
32110 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
32120 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
32130 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
32140 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
32150 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
32160 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
32170 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
32180 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
32190 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
321a0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
321b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
321c0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
321d0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
321e0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
321f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
32200 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
32210 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
32220 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
32230 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
32240 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
32250 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
32260 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
32270 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
32280 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
32290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
322a0 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
322b0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
322c0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
322d0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
322e0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
322f0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
32300 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
32310 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
32320 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
32330 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32340 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
32350 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
32360 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
32370 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
32380 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
32390 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
323a0 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
323b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
323c0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
323d0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
323e0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
323f0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
32400 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
32410 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
32420 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
32430 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
32440 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
32450 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
32460 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
32470 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
32480 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
32490 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
324a0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
324b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
324c0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
324d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
324e0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
324f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
32500 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
32510 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
32520 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
32530 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
32540 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
32550 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
32560 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
32570 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32580 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
32590 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
325a0 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
325b0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
325c0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
325d0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
325e0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
325f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
32600 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
32610 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
32620 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
32630 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
32640 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
32650 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
32660 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
32670 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
32680 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
32690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
326a0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
326b0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
326c0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
326d0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
326e0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
326f0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
32700 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
32710 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
32720 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
32730 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
32740 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
32750 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
32760 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
32770 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
32780 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32790 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
327a0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
327b0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
327c0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
327d0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
327e0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
327f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32800 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
32810 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
32820 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
32830 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
32840 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
32850 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
32860 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
32870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32880 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
32890 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
328a0 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
328b0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
328c0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
328d0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
328e0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
328f0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
32900 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
32910 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
32920 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
32930 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
32940 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
32950 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
32960 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
32970 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
32980 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
32990 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
329a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
329b0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
329c0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
329d0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
329e0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
329f0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
32a00 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
32a10 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
32a20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
32a30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
32a40 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
32a50 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
32a60 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32a70 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
32a80 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
32a90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
32aa0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
32ab0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
32ac0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
32ad0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
32ae0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
32af0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
32b00 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
32b10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32b20 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
32b30 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
32b40 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
32b50 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
32b60 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
32b70 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
32b80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
32b90 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
32ba0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
32bb0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
32bc0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
32bd0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
32be0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
32bf0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
32c00 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
32c10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
32c20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
32c30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32c40 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
32c50 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
32c60 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
32c70 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
32c80 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
32c90 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
32ca0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
32cb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32cc0 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
32cd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32ce0 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
32cf0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
32d00 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
32d10 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
32d20 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
32d30 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
32d40 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
32d50 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
32d60 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
32d70 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
32d80 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
32d90 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
32da0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
32db0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
32dc0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
32dd0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
32de0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
32df0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
32e00 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c  pointer..**.** <
32e10 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e  b>Warning:</b> ^
32e20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
32e30 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
32e40 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
32e50 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
32e60 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32e70 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e  lue] object.  In
32e80 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64   a multithreaded
32e90 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a   environment,.**
32ea0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
32eb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
32ec0 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ject may only be
32ed0 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74   used safely wit
32ee0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  h.** [sqlite3_bi
32ef0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
32f00 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32f10 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
32f20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
32f30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32f40 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
32f50 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
32f60 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
32f70 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
32f80 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
32f90 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
32fa0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
32fb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
32fc0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
32fd0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
32fe0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
32ff0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62  _bytes()], the b
33000 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74  ehavior is not t
33010 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a  hreadsafe..**.**
33020 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
33030 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
33040 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
33050 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
33060 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
33070 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
33080 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
33090 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
330a0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
330b0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
330c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
330d0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
330e0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
330f0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
33100 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
33110 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
33120 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
33130 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
33140 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
33150 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
33160 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
33170 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
33180 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
33190 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
331a0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
331b0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
331c0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
331d0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
331e0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
331f0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
33200 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
33210 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
33220 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
33230 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
33240 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
33250 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
33260 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
33270 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
33280 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
33290 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
332a0 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
332b0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
332c0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
332d0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
332e0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
332f0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
33300 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
33310 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
33320 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
33330 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
33340 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
33350 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
33360 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
33370 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
33380 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
33390 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
333a0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
333b0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
333c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
333d0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
333e0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
333f0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
33400 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
33410 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
33420 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43   BLOB    <td> [C
33430 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20  AST] to BLOB.** 
33440 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
33450 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
33460 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
33470 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
33480 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
33490 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
334a0 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
334b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
334c0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
334d0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
334e0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
334f0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
33500 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
33510 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
33520 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
33530 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
33540 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
33550 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
33560 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
33570 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
33580 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
33590 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
335a0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
335b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
335c0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
335d0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
335e0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
335f0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
33600 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
33610 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
33620 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
33630 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
33640 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
33650 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33660 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
33670 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
33680 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
33690 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
336a0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
336b0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
336c0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
336d0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
336e0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
336f0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
33700 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33710 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
33720 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33730 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
33740 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
33750 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
33760 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
33770 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
33780 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
33790 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
337a0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
337b0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
337c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
337d0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
337e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
337f0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
33800 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
33810 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
33820 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
33830 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
33840 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
33850 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
33860 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
33870 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
33880 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
33890 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
338a0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
338b0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
338c0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
338d0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
338e0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
338f0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
33900 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
33910 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
33920 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
33930 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
33940 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
33950 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
33960 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
33970 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
33980 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
33990 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
339a0 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
339b0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
339c0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
339d0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
339e0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
339f0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
33a00 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
33a10 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
33a20 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
33a30 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
33a40 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
33a50 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
33a60 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
33a70 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  est policy is to
33a80 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
33a90 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
33aa0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
33ab0 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
33ac0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
33ad0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
33ae0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
33af0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33b00 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
33b10 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
33b20 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
33b30 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
33b40 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
33b50 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
33b60 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
33b70 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
33b80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
33b90 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
33ba0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
33bb0 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
33bc0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
33bd0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
33be0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
33bf0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
33c00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33c10 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
33c20 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
33c30 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
33c40 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
33c50 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
33c60 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
33c70 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
33c80 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
33c90 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
33ca0 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
33cb0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
33cc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
33cd0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
33ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
33cf0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
33d00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
33d10 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
33d20 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
33d30 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
33d40 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
33d50 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
33d60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33d70 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
33d80 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
33d90 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
33da0 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
33db0 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
33dc0 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
33dd0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
33de0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
33df0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33e00 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
33e10 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
33e20 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
33e30 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
33e40 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
33e50 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
33e60 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
33e70 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f  ally.  Do <em>no
33e80 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20  t</em> pass the 
33e90 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
33ea0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
33eb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
33ec0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
33ed0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
33ee0 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
33ef0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
33f00 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
33f10 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
33f20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
33f30 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
33f40 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
33f50 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
33f60 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
33f70 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
33f80 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
33f90 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
33fa0 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
33fb0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
33fc0 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
33fd0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
33fe0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
33ff0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
34000 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
34010 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
34020 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
34030 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
34040 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
34050 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
34060 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
34070 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
34080 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
34090 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
340a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
340b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
340c0 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
340d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
340e0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
340f0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
34100 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
34110 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
34120 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
34130 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
34140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
34150 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
34160 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
34170 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
34180 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
34190 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
341a0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
341b0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
341c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
341d0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
341e0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
341f0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
34200 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
34210 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
34220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
34230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
34240 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
34250 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
34260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
34270 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
34280 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
34290 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52  ct.** DESTRUCTOR
342a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
342b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
342c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
342d0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
342e0 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
342f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34300 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
34310 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
34320 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
34330 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
34340 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
34350 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
34360 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
34370 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
34380 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34390 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
343a0 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
343b0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
343c0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
343d0 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
343e0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
343f0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
34400 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
34410 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
34420 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
34430 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
34440 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34450 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
34460 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
34470 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
34480 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
34490 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
344a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
344b0 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
344c0 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
344d0 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
344e0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
344f0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
34500 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
34510 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
34520 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
34530 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
34540 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
34550 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
34560 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
34570 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
34580 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
34590 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
345a0 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
345b0 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
345c0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
345d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
345e0 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
345f0 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
34600 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
34610 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
34620 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
34630 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
34640 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
34650 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
34660 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
34670 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
34680 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
34690 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
346a0 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
346b0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
346c0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
346d0 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
346e0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
346f0 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
34700 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
34710 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
34720 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
34730 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
34740 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
34750 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
34760 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
34770 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
34780 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
34790 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44  Object.** METHOD
347a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
347b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
347c0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
347d0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
347e0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
347f0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
34800 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
34810 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
34820 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
34830 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
34840 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
34850 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
34860 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
34870 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
34880 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
34890 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
348a0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
348b0 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
348c0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
348d0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
348e0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
348f0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
34900 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
34910 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
34920 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
34930 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34940 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
34950 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
34960 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
34970 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
34980 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
34990 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
349a0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
349b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
349c0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
349d0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
349e0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
349f0 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
34a00 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
34a10 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
34a20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
34a30 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
34a40 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
34a50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
34a60 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
34a70 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
34a80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
34a90 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
34aa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34ab0 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
34ac0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
34ad0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
34ae0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
34af0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
34b00 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
34b10 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
34b20 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
34b30 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
34b40 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
34b50 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
34b60 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
34b70 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
34b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
34b90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
34ba0 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
34bb0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
34bc0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
34bd0 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
34be0 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
34bf0 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
34c00 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
34c10 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
34c20 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
34c30 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
34c40 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
34c50 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
34c60 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
34c70 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
34c80 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
34c90 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
34ca0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
34cb0 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
34cc0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
34cd0 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
34ce0 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
34cf0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
34d00 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
34d10 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
34d20 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
34d30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
34d40 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
34d50 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
34d60 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
34d70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
34d80 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
34d90 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
34da0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
34db0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
34dc0 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
34dd0 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
34de0 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
34df0 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
34e00 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
34e10 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
34e20 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34e30 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
34e40 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
34e50 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
34e60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34e70 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
34e80 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
34e90 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
34ea0 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
34eb0 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
34ec0 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
34ed0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
34ee0 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
34ef0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
34f00 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
34f10 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
34f20 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
34f30 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
34f40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
34f50 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
34f60 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
34f70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
34f80 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
34f90 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
34fa0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
34fb0 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
34fc0 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
34fd0 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
34fe0 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
34ff0 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
35000 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
35010 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
35020 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
35030 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
35040 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
35050 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
35060 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
35070 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
35080 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
35090 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
350a0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
350b0 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
350c0 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
350d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
350e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
350f0 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
35100 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
35110 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
35120 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
35130 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
35140 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
35150 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
35160 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
35170 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
35180 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
35190 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
351a0 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
351b0 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
351c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
351d0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
351e0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
351f0 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
35200 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
35210 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
35220 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
35230 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
35240 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
35250 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
35260 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
35270 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
35280 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
35290 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
352a0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
352b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
352c0 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
352d0 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20  arameters.  The 
352e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
352f0 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61  ld set this para
35300 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c  meter to.** [SQL
35310 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20  ITE_UTF16LE] if 
35320 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
35330 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
35340 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  kes .** [sqlite3
35350 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
35360 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20  )] on an input, 
35370 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
35380 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d  BE] if the.** im
35390 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
353a0 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61  okes [sqlite3_va
353b0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20  lue_text16be()] 
353c0 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a  on an input, or.
353d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
353e0 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  ] if [sqlite3_va
353f0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73  lue_text16()] is
35400 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54   used, or [SQLIT
35410 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72  E_UTF8].** other
35420 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65  wise.  ^The same
35430 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61   SQL function ma
35440 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
35450 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
35460 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e  sing.** differen
35470 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  t preferred text
35480 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68   encodings, with
35490 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65   different imple
354a0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a  mentations for.*
354b0 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e  * each encoding.
354c0 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
354d0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
354e0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
354f0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
35500 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
35510 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
35520 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
35530 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
35540 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
35550 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sion..**.** ^The
35560 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
35570 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79  r may optionally
35580 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53   be ORed with [S
35590 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
355a0 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  TIC].** to signa
355b0 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74  l that the funct
355c0 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ion will always 
355d0 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
355e0 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20  result given.** 
355f0 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20  the same inputs 
35600 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20  within a single 
35610 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
35620 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  Most SQL functio
35630 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d  ns are.** determ
35640 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75  inistic.  The bu
35650 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29  ilt-in [random()
35660 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  ] SQL function i
35670 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
35680 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  a.** function th
35690 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d  at is not determ
356a0 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51  inistic.  The SQ
356b0 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e  Lite query plann
356c0 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a  er is able to.**
356d0 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f   perform additio
356e0 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  nal optimization
356f0 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74  s on determinist
35700 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f  ic functions, so
35710 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b   use.** of the [
35720 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
35730 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65  STIC] flag is re
35740 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20  commended where 
35750 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  possible..**.** 
35760 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
35770 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
35780 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
35790 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
357a0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
357b0 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
357c0 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
357d0 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
357e0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
357f0 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ].)^.**.** ^The 
35800 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61  sixth, seventh a
35810 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65  nd eighth parame
35820 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
35830 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
35840 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
35850 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
35860 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
35870 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
35880 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
35890 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
358a0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
358b0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
358c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
358d0 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
358e0 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
358f0 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70  inters must be p
35900 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
35910 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
35920 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
35930 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
35940 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
35950 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
35960 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
35970 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
35980 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20  LL pointer must 
35990 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
359a0 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20  unc. ^To delete 
359b0 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
359c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
359d0 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
359e0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72  ULL pointers for
359f0 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
35a00 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73  ion.** callbacks
35a10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65  ..**.** ^(If the
35a20 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
35a30 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
35a40 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
35a50 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
35a60 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74   then it is dest
35a70 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61  ructor for the a
35a80 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
35a90 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65  pointer. .** The
35aa0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69   destructor is i
35ab0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
35ac0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
35ad0 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62  ted, either by b
35ae0 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64  eing.** overload
35af0 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64  ed or when the d
35b00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35b10 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20  on closes.)^.** 
35b20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
35b30 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20  is also invoked 
35b40 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  if the call to.*
35b50 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
35b60 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66  _function_v2() f
35b70 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74  ails..** ^When t
35b80 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61  he destructor ca
35b90 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65  llback of the te
35ba0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  nth parameter is
35bb0 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20   invoked, it.** 
35bc0 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67  is passed a sing
35bd0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
35be0 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  h is a copy of t
35bf0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
35c00 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ata .** pointer 
35c10 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69  which was the fi
35c20 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  fth parameter to
35c30 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35c40 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  function_v2()..*
35c50 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d  *.** ^It is perm
35c60 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
35c70 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
35c80 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
35c90 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
35ca0 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
35cb0 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
35cc0 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
35cd0 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
35ce0 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
35cf0 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
35d00 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
35d10 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
35d20 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
35d30 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
35d40 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
35d50 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
35d60 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
35d70 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
35d80 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70   ^A function imp
35d90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
35da0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
35db0 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
35dc0 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
35dd0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
35de0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
35df0 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
35e00 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20  ative nArg.  ^A 
35e10 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
35e20 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
35e30 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
35e40 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
35e50 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
35e60 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
35e70 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
35e80 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
35e90 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
35ea0 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69  .  .** ^A functi
35eb0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
35ec0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
35ed0 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
35ee0 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
35ef0 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
35f00 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
35f10 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
35f20 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
35f30 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
35f40 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
35f50 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e  .**.** ^Built-in
35f60 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
35f70 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20  e overloaded by 
35f80 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  new application-
35f90 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35fa0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70  s..**.** ^An app
35fb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35fc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
35fd0 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
35fe0 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
35ff0 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
36000 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
36010 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
36020 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
36030 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
36040 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
36050 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
36060 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
36070 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
36080 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69  is running..*/.i
36090 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
360a0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
360b0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
360c0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
360d0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
360e0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
360f0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
36100 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
36110 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
36120 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
36130 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
36140 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
36150 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
36160 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
36170 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
36180 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36190 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
361a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
361b0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
361c0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
361d0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
361e0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
361f0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
36200 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
36210 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
36220 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
36230 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
36240 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
36250 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
36260 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
36270 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
36280 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
36290 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
362a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
362b0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
362c0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
362d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
362e0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
362f0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
36300 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
36310 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
36320 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
36330 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
36340 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
36350 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
36360 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
36370 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
36380 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
36390 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
363a0 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  ext*),.  void(*x
363b0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
363c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
363d0 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
363e0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
363f0 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
36400 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
36410 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
36420 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
36430 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
36440 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
36450 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36460 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
36470 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33  1    /* IMP: R-3
36480 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64  7514-35566 */.#d
36490 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
364a0 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20  16LE        2   
364b0 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31   /* IMP: R-03371
364c0 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e  -37637 */.#defin
364d0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
364e0 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20          3    /* 
364f0 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31  IMP: R-51971-341
36500 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  54 */.#define SQ
36510 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
36520 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
36530 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
36540 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
36550 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
36560 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65     5    /* Depre
36570 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  cated */.#define
36580 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
36590 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
365a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
365b0 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
365c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
365d0 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a   Function Flags.
365e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
365f0 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65  tants may be ORe
36600 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20  d together with 
36610 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
36620 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64  UTF8 | preferred
36630 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
36640 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
36650 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
36660 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36670 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ction()], [sqlit
36680 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36690 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
366a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
366b0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  unction_v2()]..*
366c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
366d0 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20  _DETERMINISTIC  
366e0 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43    0x800../*.** C
366f0 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
36700 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
36710 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
36720 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
36730 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
36740 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
36750 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
36760 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
36770 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
36780 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
36790 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
367a0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
367b0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
367c0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
367d0 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
367e0 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
367f0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65  functions.  To e
36800 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d  ncourage program
36810 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  mers to avoid.**
36820 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
36830 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78  , we will not ex
36840 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20  plain what they 
36850 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
36860 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
36870 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
36880 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
36890 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
368a0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
368b0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
368c0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
368d0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
368e0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
368f0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
36900 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
36910 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
36920 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
36930 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
36940 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
36950 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
36960 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
36970 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
36980 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
36990 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
369a0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
369b0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
369c0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
369d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
369e0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
369f0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
36a00 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71          void*,sq
36a10 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
36a20 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
36a30 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
36a40 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
36a50 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
36a60 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  lue.**.** The C-
36a70 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
36a80 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
36a90 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
36aa0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
36ab0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
36ac0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
36ad0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
36ae0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
36af0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
36b00 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20   or aggregate.  
36b10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
36b20 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
36b30 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
36b40 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
36b50 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
36b60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
36b70 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
36b80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
36b90 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
36ba0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
36bb0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
36bc0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
36bd0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
36be0 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
36bf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
36c00 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
36c10 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
36c20 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
36c30 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
36c40 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
36c50 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
36c60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36c70 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
36c80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
36c90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
36ca0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
36cb0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
36cc0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
36cd0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
36ce0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
36cf0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
36d00 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
36d10 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
36d20 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36d30 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
36d40 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
36d50 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
36d60 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
36d70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
36d80 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
36d90 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
36da0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
36db0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
36dc0 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
36dd0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
36de0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
36df0 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
36e00 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74   that these rout
36e10 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
36e20 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
36e30 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36e40 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
36e50 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
36e60 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
36e70 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
36e80 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
36e90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36ea0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36eb0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
36ec0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
36ed0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
36ee0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
36ef0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
36f00 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
36f10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
36f20 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
36f30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36f40 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
36f50 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
36f60 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
36f70 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
36f80 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
36f90 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
36fa0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
36fb0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
36fc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
36fd0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
36fe0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
36ff0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
37000 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
37010 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
37020 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
37030 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
37040 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
37050 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
37060 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
37070 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
37080 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
37090 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
370a0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
370b0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
370c0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
370d0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
370e0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
370f0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
37100 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
37110 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
37120 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
37130 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
37140 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
37150 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
37160 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
37170 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
37180 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
37190 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
371a0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
371b0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
371c0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
371d0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
371e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
371f0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
37200 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
37210 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
37220 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
37230 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
37240 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
37250 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
37260 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
37270 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
37280 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
37290 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
372a0 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
372b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
372c0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
372d0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
372e0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
372f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
37300 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
37310 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
37320 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
37330 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
37340 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
37350 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
37360 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
37370 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
37380 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
37390 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
373a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
373b0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
373c0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
373d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
373e0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
373f0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
37400 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
37410 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
37420 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
37430 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
37440 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
37450 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37460 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37470 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
37480 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37490 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
374a0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
374b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
374c0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
374d0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
374e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
374f0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
37500 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
37510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
37520 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
37530 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
37540 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
37550 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
37560 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
37570 52 45 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65  REF: Finding The
37580 20 53 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20   Subtype Of SQL 
37590 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
375a0 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
375b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
375c0 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28  3_value_subtype(
375d0 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  V) function retu
375e0 72 6e 73 20 74 68 65 20 73 75 62 74 79 70 65 20  rns the subtype 
375f0 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69  for.** an [appli
37600 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
37610 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67  QL function] arg
37620 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75  ument V.  The su
37630 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  btype.** informa
37640 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
37650 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74   to pass a limit
37660 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  ed amount of con
37670 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  text from.** one
37680 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
37690 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74   another.  Use t
376a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
376b0 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a  lt_subtype()].**
376c0 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20   routine to set 
376d0 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 20  the subtype for 
376e0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
376f0 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74   of an SQL funct
37700 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
37710 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f  e makes no use o
37720 66 20 73 75 62 74 79 70 65 20 69 74 73 65 6c 66  f subtype itself
37730 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73  .  It merely pas
37740 73 65 73 20 74 68 65 20 73 75 62 74 79 70 65 0a  ses the subtype.
37750 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75  ** from the resu
37760 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69  lt of one [appli
37770 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
37780 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74  QL function] int
37790 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f  o the.** input o
377a0 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e  f another..*/.un
377b0 73 69 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74  signed int sqlit
377c0 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65  e3_value_subtype
377d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
377e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
377f0 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65  F: Copy And Free
37800 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d   SQL Values.** M
37810 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76  ETHOD: sqlite3_v
37820 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  alue.**.** ^The 
37830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
37840 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d  p(V) interface m
37850 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
37860 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
37870 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61  e].** object D a
37880 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
37890 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70  nter to that cop
378a0 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  y.  ^The [sqlite
378b0 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65  3_value] returne
378c0 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65  d.** is a [prote
378d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
378e0 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20  ue] object even 
378f0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
37900 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  not..** ^The sql
37910 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
37920 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
37930 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73  rns NULL if V is
37940 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a   NULL or if a.**
37950 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
37960 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  on fails..**.** 
37970 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
37980 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72  ue_free(V) inter
37990 66 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73  face frees an [s
379a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
379b0 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73  ject.** previous
379c0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
379d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
379e0 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69  dup()].  ^If V i
379f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
37a00 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
37a10 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69  _value_free(V) i
37a20 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
37a30 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76  op..*/.sqlite3_v
37a40 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61  alue *sqlite3_va
37a50 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71  lue_dup(const sq
37a60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
37a70 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  oid sqlite3_valu
37a80 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76  e_free(sqlite3_v
37a90 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
37aa0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
37ab0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
37ac0 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45  on Context.** ME
37ad0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
37ae0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
37af0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
37b00 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
37b10 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
37b20 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
37b30 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
37b40 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
37b50 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
37b60 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
37b70 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
37b80 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
37b90 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
37ba0 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
37bb0 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
37bc0 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
37bd0 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
37be0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
37bf0 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
37c00 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
37c10 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
37c20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
37c30 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
37c40 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
37c50 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
37c60 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37c70 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
37c80 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
37c90 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
37ca0 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
37cb0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
37cc0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37cd0 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
37ce0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
37cf0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
37d00 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
37d10 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
37d20 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
37d30 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
37d40 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
37d50 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
37d60 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
37d70 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
37d80 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
37d90 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
37da0 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
37db0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
37dc0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
37dd0 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
37de0 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
37df0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
37e00 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
37e10 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
37e20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
37e30 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
37e40 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
37e50 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
37e60 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
37e70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37e80 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37e90 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
37ea0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
37eb0 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66  inter .** when f
37ec0 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e  irst called if N
37ed0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72   is less than or
37ee0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
37ef0 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a  r if a memory.**
37f00 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
37f10 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
37f20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
37f30 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
37f40 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
37f50 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
37f60 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
37f70 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
37f80 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
37f90 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
37fa0 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
37fb0 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
37fc0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
37fd0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37fe0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
37ff0 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
38000 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
38010 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
38020 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
38030 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
38040 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74  ion.)^  Within t
38050 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
38060 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d  ck, it is custom
38070 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d  ary to set.** N=
38080 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71  0 in calls to sq
38090 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
380a0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20  context(C,N) so 
380b0 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e  that no .** poin
380c0 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tless memory all
380d0 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a  ocations occur..
380e0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75  **.** ^SQLite au
380f0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
38100 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
38110 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71  ocated by .** sq
38120 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
38130 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74  context() when t
38140 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65  he aggregate que
38150 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
38160 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
38170 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
38180 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
38190 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
381a0 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
381b0 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
381c0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
381d0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
381e0 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20  xStep or xFinal 
381f0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
38200 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
38210 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
38220 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
38230 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
38240 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
38250 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
38260 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
38270 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
38280 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
38290 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
382a0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
382b0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
382c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
382d0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
382e0 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
382f0 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
38300 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
38310 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
38320 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
38330 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
38340 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
38350 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
38360 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
38370 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
38380 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
38390 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
383a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
383b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
383c0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
383d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
383e0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
383f0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
38400 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
38410 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
38420 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
38430 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
38440 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
38450 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
38460 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
38470 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
38480 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
38490 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
384a0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
384b0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
384c0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
384d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
384e0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
384f0 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
38500 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
38510 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
38520 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
38530 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
38540 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
38550 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
38560 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
38570 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
38580 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
38590 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
385a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
385b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
385c0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
385d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
385e0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
385f0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
38600 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
38610 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
38620 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
38630 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
38640 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
38650 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
38660 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
38670 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
38680 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
38690 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ata.** METHOD: s
386a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
386b0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
386c0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
386d0 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
386e0 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
386f0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
38700 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
38710 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
38720 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
38730 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
38740 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
38750 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
38760 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
38770 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
38780 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
38790 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
387a0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
387b0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
387c0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
387d0 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
387e0 20 77 68 65