/ Hex Artifact Content
Login

Artifact 7ad8a14995ad817af0b80cc068ecc37dbf5e79f4d99fa83404585291c3305e79:


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 49 4f 45 52 52  ine SQLITE_IOERR
5760: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
5770: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5780: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
5790: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57a0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
57b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57c0: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
57d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57e0: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
57f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5800: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
5810: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5820: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5830: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5840: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5860: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5870: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5880: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
58a0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
58b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
58c0: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
58d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
58e0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
58f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5900: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5920: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5930: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5940: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5950: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5960: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5970: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5980: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5990: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
59a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
59b0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
59c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
59d0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
59e0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
59f0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5a00: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5a10: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5a20: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5a30: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5a40: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5a50: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5a60: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5a70: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5a80: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5a90: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5aa0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5ab0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5ac0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5ad0: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5ae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5af0: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5b00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5b10: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5b20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5b30: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
5b40: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5b50: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5b60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5b70: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5b80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5b90: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5ba0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5bb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5bc0: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5bd0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5be0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5bf0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c00: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5c10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c20: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5c30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c40: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5c50: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5c60: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5c80: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5c90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ca0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5cb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5cc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5cd0: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5ce0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5cf0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5d00: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5d10: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5d20: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5d30: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5d40: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5d50: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5d60: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5d70: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5d90: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5da0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5db0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5dc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5dd0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5de0: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5df0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5e00: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5e10: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5e20: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5e30: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5e40: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5e50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5e60: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5e70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5e80: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5e90: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5ea0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5eb0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5ec0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5ed0: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5ef0: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5f00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5f10: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5f20: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5f30: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5f40: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5f50: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5f60: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5f70: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5f80: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5f90: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5fa0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5fb0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5fc0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5fd0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5fe0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5ff0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
6000: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
6010: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
6020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6030: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
6040: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
6050: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6060: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6080: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
6090: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
60a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
60b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
60c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60d0: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
60e0: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
60f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6100: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
6130: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
6140: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6160: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
6170: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
6180: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6190: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61a0: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
61b0: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
61c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61e0: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
61f0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
6200: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6210: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6230: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
6240: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6250: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6260: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#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 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
6290: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
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 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
62d0: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
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 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
6310: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
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 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6350: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
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 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
6390: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
63a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
63b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63c0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
63d0: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
63e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
63f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6400: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
6410: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
6420: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6430: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6440: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6450: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
6460: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6470: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6490: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
64a0: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
64b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
64c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
64d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
64e0: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
64f0: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
6500: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6510: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6530: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
6540: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6550: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6560: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6580: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
6590: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
65a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
65b0: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
65c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
65d0: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
65e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
65f0: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
6600: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
6610: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6620: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
6630: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6640: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6650: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
6660: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
6670: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
6680: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
6690: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
66a0: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
66b0: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
66c0: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
66d0: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
66e0: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
66f0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6700: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
6710: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6720: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
6730: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6740: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
6750: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
6760: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6770: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6780: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
6790: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
67a0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
67b0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
67c0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
67d0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
67e0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
67f0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
6800: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
6810: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6820: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6830: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
6840: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
6850: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
6860: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
6870: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
6880: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
6890: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
68a0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
68b0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
68c0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
68d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
68e0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
68f0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6900: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
6910: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
6920: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
6930: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
6940: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
6950: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6960: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6970: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
6980: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
6990: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
69a0: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
69b0: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
69c0: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
69d0: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
69e0: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
69f0: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
6a00: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
6a10: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
6a20: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
6a30: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
6a40: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
6a50: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
6a60: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
6a70: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6a80: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6a90: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c  _WHEN_OPEN.** fl
6aa0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6ab0: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
6ac0: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
6ad0: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
6ae0: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6af0: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
6b00: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
6b10: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
6b20: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
6b30: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
6b40: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
6b50: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
6b60: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
6b70: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6b80: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f  _IOCAP_BATCH_ATO
6b90: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6ba0: 6e 73 20 74 68 61 74 20 74 68 65 20 75 6e 64 65  ns that the unde
6bb0: 72 6c 79 69 6e 67 0a 2a 2a 20 66 69 6c 65 73 79  rlying.** filesy
6bc0: 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 64 6f  stem supports do
6bd0: 69 6e 67 20 6d 75 6c 74 69 70 6c 65 20 77 72 69  ing multiple wri
6be0: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 74  te operations at
6bf0: 6f 6d 69 63 61 6c 6c 79 20 77 68 65 6e 20 74 68  omically when th
6c00: 6f 73 65 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65  ose.** write ope
6c10: 72 61 74 69 6f 6e 73 20 61 72 65 20 62 72 61 63  rations are brac
6c20: 6b 65 74 65 64 20 62 79 20 5b 53 51 4c 49 54 45  keted by [SQLITE
6c30: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
6c40: 4d 49 43 5f 57 52 49 54 45 5d 20 61 6e 64 0a 2a  MIC_WRITE] and.*
6c50: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
6c60: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
6c70: 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ITE]..*/.#define
6c80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6c90: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20  OMIC            
6ca0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
6cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6cc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
6cd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6ce0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
6cf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6d00: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC1K            
6d10: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
6d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6d30: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
6d40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6d50: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
6d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6d70: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6d80: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
6d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6da0: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
6db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6dc0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
6dd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6de0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6df0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
6e00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6e10: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20  TOMIC32K        
6e20: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
6e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6e40: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
6e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6e60: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
6e70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6e80: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20  E_APPEND        
6e90: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
6ea0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6eb0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
6ec0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6ed0: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
6ee0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6ef0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6f00: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
6f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6f20: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6f30: 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31  WRITE    0x00001
6f40: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
6f50: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
6f60: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  LE              
6f70: 30 78 30 30 30 30 32 30 30 30 0a 23 64 65 66 69  0x00002000.#defi
6f80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6f90: 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 20 20 20  BATCH_ATOMIC    
6fa0: 20 20 20 20 20 20 20 30 78 30 30 30 30 34 30 30         0x0000400
6fb0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
6fc0: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
6fd0: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  Levels.**.** SQL
6fe0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
6ff0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
7000: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
7010: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
7020: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
7030: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
7040: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
7050: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
7060: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7070: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
7080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
7090: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
70a0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
70b0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
70c0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
70d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
70e0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
70f0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
7100: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
7110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
7120: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
7130: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
7140: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
7150: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a  ion Type Flags.*
7160: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
7170: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
7180: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
7190: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
71a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
71b0: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
71c0: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  nation of.** the
71d0: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
71e0: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
71f0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
7200: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
7210: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
7220: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
7230: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
7240: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
7250: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
7260: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
7270: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
7280: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
7290: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
72a0: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65  hed. If the lowe
72b0: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74  r four bits of t
72c0: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c  he flag.** equal
72d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
72e0: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  MAL, that means 
72f0: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
7300: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
7310: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72  .** If the lower
7320: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c   four bits equal
7330: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7340: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  L, that means.**
7350: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
7360: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
7370: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
7380: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74  ()..**.** Do not
7390: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c   confuse the SQL
73a0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
73b0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
73c0: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69  FULL flags.** wi
73d0: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73  th the [PRAGMA s
73e0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d  ynchronous]=NORM
73f0: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73  AL and [PRAGMA s
7400: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c  ynchronous]=FULL
7410: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54  .** settings.  T
7420: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20  he [synchronous 
7430: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e  pragma] determin
7440: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f  es when calls to
7450: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46   the.** xSync VF
7460: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61  S method occur a
7470: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f  nd applies unifo
7480: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  rmly across all 
7490: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68  platforms..** Th
74a0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
74b0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
74c0: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20  SYNC_FULL flags 
74d0: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a  determine how.**
74e0: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69   energetic or ri
74f0: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66  gorous or forcef
7500: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72  ul the sync oper
7510: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a  ations are and.*
7520: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69  * only make a di
7530: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20  fference on Mac 
7540: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61  OSX for the defa
7550: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e  ult SQLite code.
7560: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79  .** (Third-party
7570: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7580: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  ions might also 
7590: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
75a0: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
75b0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
75c0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
75d0: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f  NC_FULL, but amo
75e0: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74  ng the.** operat
75f0: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69  ing systems nati
7600: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62  vely supported b
7610: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d  y SQLite, only M
7620: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20  ac OSX.** cares 
7630: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72  about the differ
7640: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e  ence.).*/.#defin
7650: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7660: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
7670: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
7680: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
7690: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
76a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
76b0: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
76c0: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43  0x00010../*.** C
76d0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
76e0: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20  rface Open File 
76f0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20  Handle.**.** An 
7700: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7710: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
7720: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
7730: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
7740: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72  3_vfs | OS inter
7750: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e  face layer].  In
7760: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
7770: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  rface.** impleme
7780: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
7790: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
77a0: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
77b0: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
77c0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
77d0: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
77e0: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
77f0: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
7800: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
7810: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7820: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
7830: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
7840: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
7850: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
7860: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
7870: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7880: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7890: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
78a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
78b0: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
78c0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
78d0: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
78e0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
78f0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
7900: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
7910: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7920: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
7930: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
7940: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
7950: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
7960: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7970: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
7980: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
7990: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
79a0: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
79b0: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
79c0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
79d0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
79e0: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
79f0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
7a00: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
7a10: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
7a20: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
7a30: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
7a40: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
7a50: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
7a60: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
7a70: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
7a80: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7a90: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
7aa0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7ab0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74  Open] method set
7ac0: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  s the sqlite3_fi
7ad0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
7ae0: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e  ent .** to a non
7af0: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
7b00: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
7b10: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73  io_methods.xClos
7b20: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20  e method.** may 
7b30: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20  be invoked even 
7b40: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  if the [sqlite3_
7b50: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72  vfs.xOpen] repor
7b60: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
7b70: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
7b80: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
7b90: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
7ba0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
7bb0: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  led [sqlite3_vfs
7bc0: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f  .xOpen].** is fo
7bd0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  r the [sqlite3_v
7be0: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74  fs.xOpen] to set
7bf0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
7c00: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
7c10: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  nt.** to NULL..*
7c20: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
7c30: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
7c40: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
7c50: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7c60: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
7c70: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
7c80: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
7c90: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
7ca0: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ync()..** The se
7cb0: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
7cc0: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
7cd0: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b  fullsync.  The [
7ce0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7cf0: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61  ONLY].** flag ma
7d00: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20  y be ORed in to 
7d10: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
7d20: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
7d30: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e  he file.** and n
7d40: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65  ot its inode nee
7d50: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e  ds to be synced.
7d60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67  .**.** The integ
7d70: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f  er values to xLo
7d80: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
7d90: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a  () are one of.**
7da0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7db0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
7dc0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7dd0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7de0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7df0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a  LOCK_RESERVED],.
7e00: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7e10: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7e20: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
7e30: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7e40: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78  ]..** </ul>.** x
7e50: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73  Lock() increases
7e60: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f   the lock. xUnlo
7e70: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74  ck() decreases t
7e80: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20  he lock..** The 
7e90: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7ea0: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63  ck() method chec
7eb0: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64  ks whether any d
7ec0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
7ed0: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e  on,.** either in
7ee0: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72   this process or
7ef0: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
7f00: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
7f10: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a  ng a RESERVED,.*
7f20: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
7f30: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
7f40: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
7f50: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
7f60: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
7f70: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74  sts and false ot
7f80: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54  herwise..**.** T
7f90: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
7fa0: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
7fb0: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
7fc0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
7fd0: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
7fe0: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
7ff0: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
8000: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
8010: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
8020: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8030: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
8040: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
8050: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69  ument is an.** i
8060: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
8070: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
8080: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  nt is a generic 
8090: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64  pointer intended
80a0: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20   to.** point to 
80b0: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  a structure that
80c0: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67   may contain arg
80d0: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20  uments or space 
80e0: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77  in which to.** w
80f0: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75  rite return valu
8100: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75  es.  Potential u
8110: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e  ses for xFileCon
8120: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a  trol() might be.
8130: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ** functions to 
8140: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20  enable blocking 
8150: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f  locks with timeo
8160: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74  uts, to change t
8170: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74  he.** locking st
8180: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d  rategy (for exam
8190: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66  ple to use dot-f
81a0: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69  ile locks), to i
81b0: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20  nquire.** about 
81c0: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20  the status of a 
81d0: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61  lock, or to brea
81e0: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20  k stale locks.  
81f0: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f  The SQLite.** co
8200: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20  re reserves all 
8210: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
8220: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
8230: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c  n use..** A [fil
8240: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8250: 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  s | list of opco
8260: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
8270: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
8280: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
8290: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
82a0: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
82b0: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
82c0: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
82d0: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
82e0: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
82f0: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
8300: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
8310: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
8320: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
8330: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
8340: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
8350: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
8360: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
8370: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
8380: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
8390: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
83a0: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
83b0: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
83c0: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
83d0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
83e0: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
83f0: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
8400: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
8410: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
8420: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
8430: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
8440: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
8450: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
8460: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
8470: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
8480: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
8490: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
84a0: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
84b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
84c0: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
84d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
84e0: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
84f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8500: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
8510: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8520: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
8530: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8540: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
8550: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8560: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
8570: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8580: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
8590: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
85a0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
85b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
85c0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
85d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
85e0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
85f0: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
8600: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
8610: 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  IAL].** <li> [SQ
8620: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
8630: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
8640: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8650: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
8660: 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a 2a 2a 20  E_OVERWRITE].** 
8670: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8680: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a  AP_IMMUTABLE].**
8690: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
86a0: 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43  CAP_BATCH_ATOMIC
86b0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
86c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
86d0: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
86e0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
86f0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8700: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
8710: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8720: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
8730: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
8740: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
8750: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
8760: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
8770: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
8780: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
8790: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
87a0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
87b0: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
87c0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
87d0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
87e0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
87f0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8800: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
8810: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
8820: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
8830: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
8840: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
8850: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
8860: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8870: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8890: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
88a0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
88b0: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
88c0: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
88d0: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
88e0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
88f0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8900: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
8910: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
8920: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
8930: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
8940: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
8950: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
8960: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
8970: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
8980: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
8990: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
89a0: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
89b0: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
89c0: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
89d0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
89e0: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
89f0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8a00: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
8a10: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
8a20: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8a30: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
8a40: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
8a50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8a60: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8a70: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
8a80: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
8a90: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
8aa0: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8ab0: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8ac0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8ad0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8ae0: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8af0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8b00: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8b10: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8b20: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
8b30: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
8b40: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8b50: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
8b60: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
8b70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
8b80: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
8b90: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
8ba0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8bb0: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8bc0: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8bd0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8be0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8bf0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8c00: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8c10: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
8c20: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8c30: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
8c40: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
8c50: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
8c60: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8c70: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8c80: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8c90: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8ca0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8cb0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8cc0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8cd0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8ce0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8cf0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8d00: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
8d10: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8d20: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
8d30: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
8d40: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
8d50: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
8d60: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8d70: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8d80: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8d90: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8da0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8db0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8dc0: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8dd0: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8de0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8df0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8e00: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
8e10: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
8e20: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8e30: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8e40: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
8e50: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
8e60: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
8e70: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8e80: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8e90: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
8ea0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8eb0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8ec0: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8ed0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8ee0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8ef0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8f00: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
8f10: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
8f20: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
8f30: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
8f40: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
8f50: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
8f60: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
8f70: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8f80: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8f90: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8fa0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8fb0: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8fc0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8fd0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8fe0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8ff0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9000: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
9010: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
9020: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9030: 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54  LOCKSTATE]].** T
9040: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9050: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
9060: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
9070: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
9080: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
9090: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
90a0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
90b0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
90c0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
90d0: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
90e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
90f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
9100: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
9110: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
9120: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
9130: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
9140: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
9150: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
9160: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
9170: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
9180: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
9190: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
91a0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
91b0: 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76  g and is only av
91c0: 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65  ailable when the
91d0: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
91e0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
91f0: 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
9200: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9210: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
9220: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9230: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
9240: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9250: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
9260: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
9270: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
9280: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
9290: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
92a0: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
92b0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
92c0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
92d0: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
92e0: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
92f0: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
9300: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
9310: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
9320: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
9330: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
9340: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
9350: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
9360: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
9370: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
9380: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
9390: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
93a0: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
93b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
93c0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
93d0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
93e0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
93f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9400: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
9410: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
9420: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
9430: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9440: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
9450: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
9460: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
9470: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
9480: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
9490: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
94a0: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
94b0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
94c0: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
94d0: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
94e0: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
94f0: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
9500: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
9510: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
9520: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
9530: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
9540: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
9550: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
9560: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
9570: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
9580: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
9590: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
95a0: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
95b0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
95c0: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
95d0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
95e0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
95f0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9600: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
9610: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
9620: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
9630: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
9640: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
9650: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9660: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c  nection.  See al
9670: 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  so [SQLITE_FCNTL
9680: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
9690: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
96a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
96b0: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  NAL_POINTER]].**
96c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
96d0: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
96e0: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
96f0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
9700: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
9710: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9720: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
9730: 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e  d with the journ
9740: 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a  al file (either.
9750: 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b  ** the [rollback
9760: 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65   journal] or the
9770: 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f   [write-ahead lo
9780: 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63  g]) for a partic
9790: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
97a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
97b0: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
97c0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
97d0: 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  R]..**.** <li>[[
97e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
97f0: 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e  C_OMITTED]].** N
9800: 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e  o longer in use.
9810: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9820: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d  ITE_FCNTL_SYNC]]
9830: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9840: 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f  FCNTL_SYNC] opco
9850: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
9860: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
9870: 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74  Lite and.** sent
9880: 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65   to the VFS imme
9890: 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74  diately before t
98a0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
98b0: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a  is invoked on a.
98c0: 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ** database file
98d0: 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c   descriptor. Or,
98e0: 20 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65   if the xSync me
98f0: 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f  thod is not invo
9900: 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20  ked .** because 
9910: 74 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e  the user has con
9920: 66 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77  figured SQLite w
9930: 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20  ith .** [PRAGMA 
9940: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52  synchronous | PR
9950: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9960: 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f  =OFF] it is invo
9970: 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a  ked in place .**
9980: 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65   of the xSync me
9990: 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61  thod. In most ca
99a0: 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72  ses, the pointer
99b0: 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
99c0: 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69   with.** this fi
99d0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55  le-control is NU
99e0: 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20  LL. However, if 
99f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9a00: 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65  e is being synce
9a10: 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  d.** as part of 
9a20: 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65  a multi-database
9a30: 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67   commit, the arg
9a40: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20  ument points to 
9a50: 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
9a60: 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
9a70: 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61  ining the transa
9a80: 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f  ctions master-jo
9a90: 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e  urnal file name.
9aa0: 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20   VFSes that .** 
9ab0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
9ac0: 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73   signal should s
9ad0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
9ae0: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
9af0: 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f  ications .** sho
9b00: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71  uld not call [sq
9b10: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9b20: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
9b30: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
9b40: 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75  so may .** disru
9b50: 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  pt the operation
9b60: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
9b70: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
9b80: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
9b90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ba0: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
9bb0: 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68  PHASETWO]].** Th
9bc0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9bd0: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
9be0: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
9bf0: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
9c00: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
9c10: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
9c20: 20 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63   after a transac
9c30: 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f  tion has been co
9c40: 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74  mmitted immediat
9c50: 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72  ely.** but befor
9c60: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
9c70: 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65  s unlocked. VFSe
9c80: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65  s that do not ne
9c90: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a  ed this signal.*
9ca0: 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  * should silentl
9cb0: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
9cc0: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f  code. Applicatio
9cd0: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
9ce0: 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ll.** [sqlite3_f
9cf0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
9d00: 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ith this opcode 
9d10: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
9d20: 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20  disrupt the .** 
9d30: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
9d40: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
9d50: 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  es that do requi
9d60: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
9d70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9d80: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
9d90: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9da0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9db0: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
9dc0: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
9dd0: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
9de0: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
9df0: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
9e00: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
9e10: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
9e20: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
9e30: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
9e40: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
9e50: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
9e60: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
9e70: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
9e80: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9e90: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
9ea0: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
9eb0: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
9ec0: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
9ed0: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
9ee0: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
9ef0: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
9f00: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9f10: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
9f20: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
9f30: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
9f40: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
9f50: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
9f60: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
9f70: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
9f80: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
9f90: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
9fa0: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
9fb0: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
9fc0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
9fd0: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
9fe0: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
9ff0: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
a000: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
a010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
a020: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
a030: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
a040: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
a050: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
a060: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
a070: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
a080: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 73 20  irst integer is 
a090: 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f  the new retry co
a0a0: 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  unt and the seco
a0b0: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73  nd.** integer is
a0c0: 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20   the delay.  If 
a0d0: 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69  either integer i
a0e0: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
a0f0: 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
a100: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62  is not changed b
a110: 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70  ut instead the p
a120: 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
a130: 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72  at setting is wr
a140: 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68  itten.** into th
a150: 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61  e array entry, a
a160: 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72  llowing the curr
a170: 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e  ent retry settin
a180: 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65  gs to be.** inte
a190: 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a  rrogated.  The z
a1a0: 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  DbName parameter
a1b0: 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
a1c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a1d0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
a1e0: 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  L]].** ^The [SQL
a1f0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
a200: 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73  T_WAL] opcode is
a210: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
a220: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
a230: 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57  sistent [WAL | W
a240: 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20  rite Ahead Log] 
a250: 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66  setting.  By def
a260: 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69  ault, the auxili
a270: 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65  ary.** write ahe
a280: 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65  ad log and share
a290: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75  d memory files u
a2a0: 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74  sed for transact
a2b0: 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61  ion control.** a
a2c0: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
a2d0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
a2e0: 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74  e latest connect
a2f0: 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62  ion to the datab
a300: 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20  ase.** closes.  
a310: 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65  Setting persiste
a320: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73  nt WAL mode caus
a330: 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74  es those files t
a340: 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a  o persist after.
a350: 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69  ** close.  Persi
a360: 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20  sting the files 
a370: 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f  is useful when o
a380: 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74  ther processes t
a390: 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61  hat do not.** ha
a3a0: 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73  ve write permiss
a3b0: 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63  ion on the direc
a3c0: 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  tory containing 
a3d0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a3e0: 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61  e want.** to rea
a3f0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  d the database f
a400: 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20  ile, as the WAL 
a410: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
a420: 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69  y files must exi
a430: 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66  st.** in order f
a440: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
a450: 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20  to be readable. 
a460: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
a470: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
a480: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a490: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
a4a0: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
a4b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
a4c0: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
a4d0: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
a4e0: 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65  disable persiste
a4f0: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31  nt WAL mode or 1
a500: 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69   to enable persi
a510: 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64  stent.** WAL mod
a520: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
a530: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
a540: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
a550: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
a560: 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74  t.** WAL persist
a570: 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  ence setting..**
a580: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a590: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a5a0: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
a5b0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a5c0: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
a5d0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a5e0: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
a5f0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
a600: 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73  rsistent "powers
a610: 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f  afe-overwrite" o
a620: 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67  r "PSOW" setting
a630: 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74  .  The PSOW sett
a640: 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65  ing.** determine
a650: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f  s the [SQLITE_IO
a660: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
a670: 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20  ERWRITE] bit of 
a680: 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68  the.** xDeviceCh
a690: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
a6a0: 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74  thods. The fourt
a6b0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a6c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a6d0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a6e0: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a6f0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a700: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a710: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a720: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65   0 to disable ze
a730: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f  ro-damage mode o
a740: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65  r 1 to enable ze
a750: 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64  ro-damage.** mod
a760: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
a770: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
a780: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
a790: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
a7a0: 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65  t.** zero-damage
a7b0: 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a   mode setting..*
a7c0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a7d0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a7e0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a7f0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a800: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  ITE] opcode is i
a810: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
a820: 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a   after opening.*
a830: 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61  * a write transa
a840: 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74  ction to indicat
a850: 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69  e that, unless i
a860: 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t is rolled back
a870: 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61   for some.** rea
a880: 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20  son, the entire 
a890: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
a8a0: 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ll be overwritte
a8b0: 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  n by the current
a8c0: 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e   .** transaction
a8d0: 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62  . This is used b
a8e0: 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69  y VACUUM operati
a8f0: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ons..**.** <li>[
a900: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a910: 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  SNAME]].** ^The 
a920: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a930: 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61  SNAME] opcode ca
a940: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
a950: 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
a960: 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20  .** all [VFSes] 
a970: 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b  in the VFS stack
a980: 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65  .  The names are
a990: 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d   of all VFS shim
a9a0: 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e  s and the.** fin
a9b0: 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20  al bottom-level 
a9c0: 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20  VFS are written 
a9d0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
a9e0: 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
a9f0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
aa00: 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20   and the result 
aa10: 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  is stored in the
aa20: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a   char* variable.
aa30: 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72  ** that the four
aa40: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
aa50: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
aa60: 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20  ntrol()] points 
aa70: 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65  to..** The calle
aa80: 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  r is responsible
aa90: 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65   for freeing the
aaa0: 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e   memory when don
aab0: 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61  e.  As with.** a
aac0: 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ll file-control 
aad0: 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69  actions, there i
aae0: 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74  s no guarantee t
aaf0: 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63  hat this will ac
ab00: 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79  tually.** do any
ab10: 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20  thing.  Callers 
ab20: 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a  should initializ
ab30: 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  e the char* vari
ab40: 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  able to a NULL.*
ab50: 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73  * pointer in cas
ab60: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
ab70: 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  rol is not imple
ab80: 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69  mented.  This fi
ab90: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73  le-control.** is
aba0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69   intended for di
abb0: 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c  agnostic use onl
abc0: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
abd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
abe0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68  POINTER]].** ^Th
abf0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ac00: 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  VFS_POINTER] opc
ac10: 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e  ode finds a poin
ac20: 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c  ter to the top-l
ac30: 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20  evel.** [VFSes] 
ac40: 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65  currently in use
ac50: 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e  .  ^(The argumen
ac60: 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65  t X in.** sqlite
ac70: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64  3_file_control(d
ac80: 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  b,SQLITE_FCNTL_V
ac90: 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75  FS_POINTER,X) mu
aca0: 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65  st be.** of type
acb0: 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20   "[sqlite3_vfs] 
acc0: 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64  **".  This opcod
acd0: 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a  es will set *X.*
ace0: 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74  * to a pointer t
acf0: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20  o the top-level 
ad00: 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20  VFS.)^.** ^When 
ad10: 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70  there are multip
ad20: 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20  le VFS shims in 
ad30: 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20  the stack, this 
ad40: 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65  opcode finds the
ad50: 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73  .** upper-most s
ad60: 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  him only..**.** 
ad70: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ad80: 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e  TL_PRAGMA]].** ^
ad90: 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47  Whenever a [PRAG
ada0: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  MA] statement is
adb0: 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c   parsed, an [SQL
adc0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
add0: 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  ] .** file contr
ade0: 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68  ol is sent to th
adf0: 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e open [sqlite3_
ae00: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72  file] object cor
ae10: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f  responding.** to
ae20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
ae30: 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  le to which the 
ae40: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
ae50: 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72   refers. ^The ar
ae60: 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
ae70: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
ae80: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
ae90: 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20  rol is an array 
aea0: 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  of.** pointers t
aeb0: 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a  o strings (char*
aec0: 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  *) in which the 
aed0: 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f  second element o
aee0: 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69  f the array.** i
aef0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
af00: 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65  e pragma and the
af10: 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69   third element i
af20: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
af30: 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20  o the.** pragma 
af40: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70  or NULL if the p
af50: 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67  ragma has no arg
af60: 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e  ument.  ^The han
af70: 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b  dler for an.** [
af80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
af90: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
afa0: 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79  l can optionally
afb0: 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20   make the first 
afc0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  element.** of th
afd0: 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e  e char** argumen
afe0: 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  t point to a str
aff0: 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
b000: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
b010: 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20  tf()].** or the 
b020: 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74  equivalent and t
b030: 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  hat string will 
b040: 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c  become the resul
b050: 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  t of the pragma 
b060: 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  or.** the error 
b070: 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70  message if the p
b080: 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66  ragma fails. ^If
b090: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
b0a0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b0b0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b0c0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ns [SQLITE_NOTFO
b0d0: 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61  UND], then norma
b0e0: 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70  l .** [PRAGMA] p
b0f0: 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e  rocessing contin
b100: 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ues.  ^If the [S
b110: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b120: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
b130: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
b140: 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68  ITE_OK], then th
b150: 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73  e parser assumes
b160: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53   that the.** VFS
b170: 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65   has handled the
b180: 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61   PRAGMA itself a
b190: 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65  nd the parser ge
b1a0: 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a  nerates a no-op.
b1b0: 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
b1c0: 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20  ement if result 
b1d0: 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20  string is NULL, 
b1e0: 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e 73 20  or that returns 
b1f0: 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
b200: 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69   result string i
b210: 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 20  f the string is 
b220: 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66  non-NULL..** ^If
b230: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b240: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b250: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a  control returns.
b260: 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f  ** any result co
b270: 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  de other than [S
b280: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51  QLITE_OK] or [SQ
b290: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
b2a0: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  that means.** th
b2b0: 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75  at the VFS encou
b2c0: 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20  ntered an error 
b2d0: 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74  while handling t
b2e0: 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20  he [PRAGMA] and 
b2f0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69  the.** compilati
b300: 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41  on of the PRAGMA
b310: 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65   fails with an e
b320: 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c  rror.  ^The [SQL
b330: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b340: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
b350: 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20  l occurs at the 
b360: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61  beginning of pra
b370: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  gma statement an
b380: 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a  alysis and so.**
b390: 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f   it is able to o
b3a0: 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e  verride built-in
b3b0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
b3c0: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ents..**.** <li>
b3d0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
b3e0: 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20  USYHANDLER]].** 
b3f0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
b400: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a  TL_BUSYHANDLER].
b410: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b420: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62  may be invoked b
b430: 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20  y SQLite on the 
b440: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61  database file ha
b450: 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20  ndle.** shortly 
b460: 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e  after it is open
b470: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  ed in order to p
b480: 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20  rovide a custom 
b490: 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a  VFS with access.
b4a0: 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63  ** to the connec
b4b0: 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c  tions busy-handl
b4c0: 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65  er callback. The
b4d0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20   argument is of 
b4e0: 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a  type (void **).*
b4f0: 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20  * - an array of 
b500: 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c  two (void *) val
b510: 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28  ues. The first (
b520: 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79  void *) actually
b530: 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20   points.** to a 
b540: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
b550: 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a   (int (*)(void *
b560: 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  )). In order to 
b570: 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65  invoke the conne
b580: 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68  ctions.** busy-h
b590: 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e  andler, this fun
b5a0: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ction should be 
b5b0: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65  invoked with the
b5c0: 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29   second (void *)
b5d0: 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79   in.** the array
b5e0: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67   as the only arg
b5f0: 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74  ument. If it ret
b600: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
b610: 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f  hen the operatio
b620: 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
b630: 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65  etried. If it re
b640: 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
b650: 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c  custom VFS shoul
b660: 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a  d abandon the.**
b670: 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
b680: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  on..**.** <li>[[
b690: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b6a0: 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  PFILENAME]].** ^
b6b0: 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  Application can 
b6c0: 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49  invoke the [SQLI
b6d0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b6e0: 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74  ENAME] file-cont
b6f0: 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53  rol.** to have S
b700: 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61  QLite generate a
b710: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
b720: 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65  lename using the
b730: 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
b740: 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64  that is followed
b750: 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20   to generate.** 
b760: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
b770: 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62  mes for TEMP tab
b780: 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e  les and other in
b790: 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68  ternal uses.  Th
b7a0: 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  e.** argument sh
b7b0: 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a  ould be a char**
b7c0: 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66   which will be f
b7d0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66  illed with the f
b7e0: 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74  ilename.** writt
b7f0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
b800: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
b810: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
b820: 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f    The caller sho
b830: 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73  uld.** invoke [s
b840: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
b850: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20  n the result to 
b860: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c  avoid a memory l
b870: 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  eak..**.** <li>[
b880: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
b890: 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  AP_SIZE]].** The
b8a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
b8b0: 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
b8c0: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74  ontrol is used t
b8d0: 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74  o query or set t
b8e0: 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75  he.** maximum nu
b8f0: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68  mber of bytes th
b900: 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  at will be used 
b910: 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65  for memory-mappe
b920: 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72  d I/O..** The ar
b930: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
b940: 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f  ter to a value o
b950: 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69  f type sqlite3_i
b960: 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20  nt64 that.** is 
b970: 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69  an advisory maxi
b980: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b990: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20  tes in the file 
b9a0: 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20  to memory map.  
b9b0: 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  The.** pointer i
b9c0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
b9d0: 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65  th the old value
b9e0: 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  .  The limit is 
b9f0: 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a  not changed if.*
ba00: 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67  * the value orig
ba10: 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74  inally pointed t
ba20: 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61  o is negative, a
ba30: 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e  nd so the curren
ba40: 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20  t limit .** can 
ba50: 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61  be queried by pa
ba60: 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74  ssing in a point
ba70: 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65  er to a negative
ba80: 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a   number.  This.*
ba90: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  * file-control i
baa0: 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
bab0: 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  y to implement [
bac0: 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
bad0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
bae0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
baf0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bb00: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  TE_FCNTL_TRACE] 
bb10: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f  file control pro
bb20: 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69  vides advisory i
bb30: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f  nformation.** to
bb40: 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77   the VFS about w
bb50: 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c  hat the higher l
bb60: 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c  ayers of the SQL
bb70: 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f  ite stack are do
bb80: 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c  ing..** This fil
bb90: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
bba0: 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63  d by some VFS ac
bbb0: 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b  tivity tracing [
bbc0: 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  shims]..** The a
bbd0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72  rgument is a zer
bbe0: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
bbf0: 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79  ing.  Higher lay
bc00: 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51  ers in the.** SQ
bc10: 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67  Lite stack may g
bc20: 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65  enerate instance
bc30: 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63  s of this file c
bc40: 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65  ontrol if.** the
bc50: 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e   [SQLITE_USE_FCN
bc60: 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  TL_TRACE] compil
bc70: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
bc80: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
bc90: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bca0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a  TL_HAS_MOVED]].*
bcb0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bcc0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66  NTL_HAS_MOVED] f
bcd0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65  ile control inte
bce0: 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d  rprets its argum
bcf0: 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e  ent as a.** poin
bd00: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
bd10: 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20  r and it writes 
bd20: 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74  a boolean into t
bd30: 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65  hat integer depe
bd40: 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74  nding.** on whet
bd50: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66  her or not the f
bd60: 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e  ile has been ren
bd70: 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20  amed, moved, or 
bd80: 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74  deleted since it
bd90: 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70  .** was first op
bda0: 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ened..**.** <li>
bdb0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
bdc0: 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d  IN32_GET_HANDLE]
bdd0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bde0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
bdf0: 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20  _HANDLE] opcode 
be00: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
be10: 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64  btain the.** und
be20: 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66  erlying native f
be30: 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63  ile handle assoc
be40: 69 61 74 65 64 20 77 69 74 68 20 61 20 66 69 6c  iated with a fil
be50: 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20  e handle.  This 
be60: 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20  file.** control 
be70: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
be80: 72 67 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69  rgument as a poi
be90: 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65  nter to a native
bea0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64   file handle and
beb0: 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 65 20 72  .** writes the r
bec0: 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74  esulting value t
bed0: 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  here..**.** <li>
bee0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
bef0: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
bf00: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bf10: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
bf20: 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20  _HANDLE] opcode 
bf30: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
bf40: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
bf50: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
bf60: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
bf70: 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68  ethod to swap th
bf80: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69  e file handle wi
bf90: 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f  th the one.** po
bfa0: 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
bfb0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20  pArg argument.  
bfc0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20  This capability 
bfd0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
bfe0: 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e  esting.** and on
bff0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
c000: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
c010: 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66  LITE_TEST is def
c020: 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ined..**.** <li>
c030: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
c040: 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68  AL_BLOCK]].** Th
c050: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c060: 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20  WAL_BLOCK] is a 
c070: 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46  signal to the VF
c080: 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 74 20  S layer that it 
c090: 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61  might.** be adva
c0a0: 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63  ntageous to bloc
c0b0: 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41  k on the next WA
c0c0: 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f  L lock if the lo
c0d0: 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69  ck is not immedi
c0e0: 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62  ately.** availab
c0f0: 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62  le.  The WAL sub
c100: 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 74 68  system issues th
c110: 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67  is signal during
c120: 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73   rare.** circums
c130: 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20  tances in order 
c140: 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d  to fix a problem
c150: 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 20 69   with priority i
c160: 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70  nversion..** App
c170: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
c180: 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73   <em>not</em> us
c190: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
c1a0: 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  rol..**.** <li>[
c1b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
c1c0: 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  PVFS]].** The [S
c1d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
c1e0: 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d  FS] opcode is im
c1f0: 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70  plemented by zip
c200: 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74  vfs only. All ot
c210: 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c  her.** VFS shoul
c220: 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  d return SQLITE_
c230: 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69  NOTFOUND for thi
c240: 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  s opcode..**.** 
c250: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c260: 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20  TL_RBU]].** The 
c270: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
c280: 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70  U] opcode is imp
c290: 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20  lemented by the 
c2a0: 73 70 65 63 69 61 6c 20 56 46 53 20 75 73 65 64  special VFS used
c2b0: 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65   by.** the RBU e
c2c0: 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20  xtension only.  
c2d0: 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68  All other VFS sh
c2e0: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49  ould return SQLI
c2f0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a  TE_NOTFOUND for.
c300: 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  ** this opcode. 
c310: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
c320: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
c330: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a  _ATOMIC_WRITE]].
c340: 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54  ** If the [SQLIT
c350: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
c360: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f  OMIC_WRITE] opco
c370: 64 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  de returns SQLIT
c380: 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  E_OK, then.** th
c390: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
c3a0: 72 20 69 73 20 70 6c 61 63 65 64 20 69 6e 20 22  r is placed in "
c3b0: 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65  batch write mode
c3c0: 22 2c 20 77 68 69 63 68 0a 2a 2a 20 6d 65 61 6e  ", which.** mean
c3d0: 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  s all subsequent
c3e0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
c3f0: 73 20 77 69 6c 6c 20 62 65 20 64 65 66 65 72 72  s will be deferr
c400: 65 64 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a 20 61  ed and done.** a
c410: 74 6f 6d 69 63 61 6c 6c 79 20 61 74 20 74 68 65  tomically at the
c420: 20 6e 65 78 74 20 5b 53 51 4c 49 54 45 5f 46 43   next [SQLITE_FC
c430: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c440: 43 5f 57 52 49 54 45 5d 2e 20 20 53 79 73 74 65  C_WRITE].  Syste
c450: 6d 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 6e 6f  ms.** that do no
c460: 74 20 73 75 70 70 6f 72 74 20 62 61 74 63 68 20  t support batch 
c470: 61 74 6f 6d 69 63 20 77 72 69 74 65 73 20 77 69  atomic writes wi
c480: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
c490: 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 20 5e 46  _NOTFOUND..** ^F
c4a0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 75 63 63 65  ollowing a succe
c4b0: 73 73 66 75 6c 20 53 51 4c 49 54 45 5f 46 43 4e  ssful SQLITE_FCN
c4c0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
c4d0: 57 52 49 54 45 20 61 6e 64 20 70 72 69 6f 72 20  WRITE and prior 
c4e0: 74 6f 0a 2a 2a 20 74 68 65 20 63 6c 6f 73 69 6e  to.** the closin
c4f0: 67 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  g [SQLITE_FCNTL_
c500: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
c510: 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  ITE] or.** [SQLI
c520: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
c530: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2c  K_ATOMIC_WRITE],
c540: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6d 61 6b   SQLite will mak
c550: 65 0a 2a 2a 20 6e 6f 20 56 46 53 20 69 6e 74 65  e.** no VFS inte
c560: 72 66 61 63 65 20 63 61 6c 6c 73 20 6f 6e 20 74  rface calls on t
c570: 68 65 20 73 61 6d 65 20 5b 73 71 6c 69 74 65 33  he same [sqlite3
c580: 5f 66 69 6c 65 5d 20 66 69 6c 65 20 64 65 73 63  _file] file desc
c590: 72 69 70 74 6f 72 0a 2a 2a 20 65 78 63 65 70 74  riptor.** except
c5a0: 20 66 6f 72 20 63 61 6c 6c 73 20 74 6f 20 74 68   for calls to th
c5b0: 65 20 78 57 72 69 74 65 20 6d 65 74 68 6f 64 20  e xWrite method 
c5c0: 61 6e 64 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  and the xFileCon
c5d0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 77  trol method.** w
c5e0: 69 74 68 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  ith [SQLITE_FCNT
c5f0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 2e 0a 2a 2a  L_SIZE_HINT]..**
c600: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c610: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
c620: 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20  OMIC_WRITE]].** 
c630: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c640: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
c650: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61  WRITE] opcode ca
c660: 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a  uses all write.*
c670: 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e  * operations sin
c680: 63 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  ce the previous 
c690: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
c6a0: 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  to .** [SQLITE_F
c6b0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
c6c0: 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20 70  C_WRITE] to be p
c6d0: 65 72 66 6f 72 6d 65 64 20 61 74 6f 6d 69 63 61  erformed atomica
c6e0: 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c  lly..** This fil
c6f0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
c700: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  s [SQLITE_OK] if
c710: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
c720: 20 77 72 69 74 65 73 20 77 65 72 65 0a 2a 2a 20   writes were.** 
c730: 61 6c 6c 20 70 65 72 66 6f 72 6d 65 64 20 73 75  all performed su
c740: 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 68  ccessfully and h
c750: 61 76 65 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  ave been committ
c760: 65 64 20 74 6f 20 70 65 72 73 69 73 74 65 6e 74  ed to persistent
c770: 20 73 74 6f 72 61 67 65 2e 0a 2a 2a 20 5e 52 65   storage..** ^Re
c780: 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
c790: 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 69 73  her or not it is
c7a0: 20 73 75 63 63 65 73 73 66 75 6c 2c 20 74 68 69   successful, thi
c7b0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 74  s file control t
c7c0: 61 6b 65 73 0a 2a 2a 20 74 68 65 20 66 69 6c 65  akes.** the file
c7d0: 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20   descriptor out 
c7e0: 6f 66 20 62 61 74 63 68 20 77 72 69 74 65 20 6d  of batch write m
c7f0: 6f 64 65 20 73 6f 20 74 68 61 74 20 61 6c 6c 20  ode so that all 
c800: 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 77 72  subsequent.** wr
c810: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
c820: 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a  re independent..
c830: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
c840: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c  never invoke SQL
c850: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c860: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 77 69  _ATOMIC_WRITE wi
c870: 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f 72  thout.** a prior
c880: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
c890: 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   to [SQLITE_FCNT
c8a0: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
c8b0: 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  RITE]..**.** <li
c8c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c8d0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
c8e0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  WRITE]].** The [
c8f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
c900: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
c910: 54 45 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65  TE] opcode cause
c920: 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f  s all write.** o
c930: 70 65 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20  perations since 
c940: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 75 63  the previous suc
c950: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
c960: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
c970: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
c980: 52 49 54 45 5d 20 74 6f 20 62 65 20 72 6f 6c 6c  RITE] to be roll
c990: 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 69  ed back..** ^Thi
c9a0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 74  s file control t
c9b0: 61 6b 65 73 20 74 68 65 20 66 69 6c 65 20 64 65  akes the file de
c9c0: 73 63 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20  scriptor out of 
c9d0: 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65  batch write mode
c9e0: 0a 2a 2a 20 73 6f 20 74 68 61 74 20 61 6c 6c 20  .** so that all 
c9f0: 73 75 62 73 65 71 75 65 6e 74 20 77 72 69 74 65  subsequent write
ca00: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
ca10: 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20  independent..** 
ca20: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
ca30: 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45  er invoke SQLITE
ca40: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
ca50: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 77 69 74  ATOMIC_WRITE wit
ca60: 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20  hout.** a prior 
ca70: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
ca80: 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  to [SQLITE_FCNTL
ca90: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
caa0: 49 54 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ITE]..** </ul>.*
cab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cac0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
cad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
cae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
caf0: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
cb00: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a  OXYFILE       2.
cb10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cb20: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
cb30: 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23  XYFILE       3.#
cb40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cb50: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  NTL_LAST_ERRNO  
cb60: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
cb70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cb80: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
cb90: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
cba0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cbb0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
cbc0: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
cbd0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cbe0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
cbf0: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
cc00: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cc10: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
cc20: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
cc30: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
cc40: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
cc50: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
cc60: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
cc70: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
cc80: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
cc90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
cca0: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
ccb0: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
ccc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
ccd0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
cce0: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
ccf0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
cd00: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
cd10: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
cd20: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
cd30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
cd40: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
cd50: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
cd60: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
cd70: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
cd80: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
cd90: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
cda0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
cdb0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
cdc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
cdd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cde0: 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20  FCNTL_TRACE     
cdf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a               19.
ce00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ce10: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20  CNTL_HAS_MOVED  
ce20: 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23              20.#
ce30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ce40: 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20  NTL_SYNC        
ce50: 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64             21.#d
ce60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ce70: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
ce80: 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65  WO        22.#de
ce90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cea0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
ceb0: 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66  LE       23.#def
cec0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ced0: 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20  _WAL_BLOCK      
cee0: 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69          24.#defi
cef0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cf00: 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20  ZIPVFS          
cf10: 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e         25.#defin
cf20: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  e SQLITE_FCNTL_R
cf30: 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20  BU              
cf40: 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65        26.#define
cf50: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
cf60: 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  S_POINTER       
cf70: 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20       27.#define 
cf80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
cf90: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20  RNAL_POINTER    
cfa0: 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53      28.#define S
cfb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
cfc0: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_GET_HANDLE    
cfd0: 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51     29.#define SQ
cfe0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20  LITE_FCNTL_PDB  
cff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d000: 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    30.#define SQL
d010: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
d020: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20  ATOMIC_WRITE    
d030: 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   31.#define SQLI
d040: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
d050: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20  ATOMIC_WRITE    
d060: 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  32.#define SQLIT
d070: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b  E_FCNTL_ROLLBACK
d080: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 33  _ATOMIC_WRITE  3
d090: 33 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64  3../* deprecated
d0a0: 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e   names */.#defin
d0b0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
d0c0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
d0d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
d0e0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23  _LOCKPROXYFILE.#
d0f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
d100: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
d110: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
d120: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
d130: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
d140: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
d150: 20 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45            SQLITE
d160: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
d170: 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  O.../*.** CAPI3R
d180: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
d190: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
d1a0: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
d1b0: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
d1c0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
d1d0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
d1e0: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
d1f0: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
d200: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
d210: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
d220: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
d230: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
d240: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
d250: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
d260: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
d270: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
d280: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
d290: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
d2a0: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
d2b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
d2c0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
d2d0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d2e0: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
d2f0: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
d300: 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62  CAPI3REF: Loadab
d310: 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75  le Extension Thu
d320: 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74  nk.**.** A point
d330: 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65  er to the opaque
d340: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
d350: 74 69 6e 65 73 20 73 74 72 75 63 74 75 72 65 20  tines structure 
d360: 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20  is passed as.** 
d370: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
d380: 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69  ter to entry poi
d390: 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65  nts of [loadable
d3a0: 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54   extensions].  T
d3b0: 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  his.** structure
d3c0: 20 6d 75 73 74 20 62 65 20 74 79 70 65 64 65 66   must be typedef
d3d0: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77  ed in order to w
d3e0: 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69  ork around compi
d3f0: 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20  ler warnings.** 
d400: 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d  on some platform
d410: 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
d420: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69  ruct sqlite3_api
d430: 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65  _routines sqlite
d440: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a  3_api_routines;.
d450: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d460: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
d470: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
d480: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
d490: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
d4a0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
d4b0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
d4c0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
d4d0: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
d4e0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
d4f0: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
d500: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
d510: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
d520: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
d530: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
d540: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
d550: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
d560: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
d570: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
d580: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
d590: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
d5a0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
d5b0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
d5c0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
d5d0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
d5e0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
d5f0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
d600: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
d610: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
d620: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
d630: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
d640: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
d650: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
d660: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
d670: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
d680: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
d690: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
d6a0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
d6b0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
d6c0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
d6d0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
d6e0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
d6f0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
d700: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
d710: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
d720: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
d730: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
d740: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
d750: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
d760: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
d770: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
d780: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
d790: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
d7a0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
d7b0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
d7c0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
d7d0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
d7e0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
d7f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
d800: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
d810: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
d820: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
d830: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
d840: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
d850: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
d860: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
d870: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
d880: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
d890: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
d8a0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
d8b0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
d8c0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
d8d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
d8e0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
d8f0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
d900: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
d910: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
d920: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
d930: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
d940: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
d950: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
d960: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
d970: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
d980: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
d990: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
d9a0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
d9b0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
d9c0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
d9d0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
d9e0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
d9f0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
da00: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
da10: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
da20: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
da30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
da40: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
da50: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
da60: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
da70: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
da80: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
da90: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
daa0: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
dab0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
dac0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
dad0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
dae0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
daf0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
db00: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
db10: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
db20: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
db30: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
db40: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
db50: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
db60: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
db70: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
db80: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
db90: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
dba0: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
dbb0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
dbc0: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
dbd0: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
dbe0: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
dbf0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
dc00: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
dc10: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
dc20: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
dc30: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
dc40: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
dc50: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
dc60: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
dc70: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
dc80: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
dc90: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
dca0: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
dcb0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
dcc0: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
dcd0: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
dce0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
dcf0: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
dd00: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
dd10: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
dd20: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
dd30: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
dd40: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
dd50: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
dd60: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
dd70: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
dd80: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
dd90: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
dda0: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
ddb0: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
ddc0: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
ddd0: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
dde0: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
ddf0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
de00: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
de10: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
de20: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
de30: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
de40: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
de50: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
de60: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
de70: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
de80: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
de90: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
dea0: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
deb0: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
dec0: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
ded0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
dee0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
def0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
df00: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
df10: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
df20: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
df30: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
df40: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
df50: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
df60: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
df70: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
df80: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
df90: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
dfa0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
dfb0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
dfc0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
dfd0: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
dfe0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
dff0: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
e000: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
e010: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e020: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
e030: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e040: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
e050: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
e060: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
e070: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e080: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
e090: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e0a0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
e0b0: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
e0c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
e0d0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
e0e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
e0f0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
e100: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e110: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
e120: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
e130: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
e140: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
e150: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
e160: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
e170: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
e180: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
e190: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
e1a0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
e1b0: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
e1c0: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
e1d0: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
e1e0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
e1f0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
e200: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
e210: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
e220: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
e230: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
e240: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
e250: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
e260: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
e270: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
e280: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
e290: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
e2a0: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
e2b0: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
e2c0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
e2d0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
e2e0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
e2f0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
e300: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
e310: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
e320: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
e330: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
e340: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
e350: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
e360: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
e370: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
e380: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
e390: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
e3a0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
e3b0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
e3c0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
e3d0: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
e3e0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
e3f0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e400: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
e410: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
e420: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
e430: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
e440: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
e450: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
e460: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
e470: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
e480: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
e490: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
e4a0: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
e4b0: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
e4c0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
e4d0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
e4e0: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
e4f0: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
e500: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
e510: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
e520: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
e530: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
e540: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
e550: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
e560: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
e570: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
e580: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
e590: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
e5a0: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
e5b0: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
e5c0: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
e5d0: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
e5e0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
e5f0: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
e600: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
e610: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
e620: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
e630: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
e640: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
e650: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
e660: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
e670: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
e680: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
e690: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
e6a0: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
e6b0: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
e6c0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
e6d0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
e6e0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
e6f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
e700: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
e710: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
e720: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
e730: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
e740: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
e750: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
e760: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
e770: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
e780: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
e790: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
e7a0: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
e7b0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
e7c0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
e7d0: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
e7e0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
e7f0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
e800: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
e810: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
e820: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
e830: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
e840: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
e850: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
e860: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
e870: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
e880: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
e890: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
e8a0: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
e8b0: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
e8c0: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
e8d0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
e8e0: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
e8f0: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
e900: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
e910: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
e920: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
e930: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
e940: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
e950: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
e960: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e970: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
e980: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
e990: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
e9a0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
e9b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
e9c0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
e9d0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
e9e0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
e9f0: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
ea00: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
ea10: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
ea20: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
ea30: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
ea40: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
ea50: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
ea60: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
ea70: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
ea80: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
ea90: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
eaa0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
eab0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
eac0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
ead0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
eae0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
eaf0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
eb00: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
eb10: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
eb20: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
eb30: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
eb40: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
eb50: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
eb60: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
eb70: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
eb80: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
eb90: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
eba0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
ebb0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
ebc0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
ebd0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
ebe0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
ebf0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
ec00: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
ec10: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
ec20: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
ec30: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
ec40: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
ec50: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
ec60: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
ec70: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
ec80: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
ec90: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
eca0: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
ecb0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
ecc0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
ecd0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
ece0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
ecf0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
ed00: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
ed10: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
ed20: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
ed30: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
ed40: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
ed50: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
ed60: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
ed70: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
ed80: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
ed90: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
eda0: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
edb0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
edc0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
edd0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
ede0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
edf0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
ee00: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
ee10: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
ee20: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
ee30: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
ee40: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
ee50: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
ee60: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
ee70: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
ee80: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
ee90: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
eea0: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
eeb0: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
eec0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
eed0: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
eee0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
eef0: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
ef00: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
ef10: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
ef20: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
ef30: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
ef40: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
ef50: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
ef60: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
ef70: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
ef80: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
ef90: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
efa0: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
efb0: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
efc0: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
efd0: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
efe0: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
eff0: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
f000: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
f010: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
f020: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
f030: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
f040: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
f050: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
f060: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
f070: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
f080: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
f090: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
f0a0: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
f0b0: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
f0c0: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
f0d0: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
f0e0: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
f0f0: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
f100: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
f110: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
f120: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
f130: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
f140: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
f150: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
f160: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
f170: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
f180: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
f190: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
f1a0: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
f1b0: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
f1c0: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
f1d0: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
f1e0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
f1f0: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
f200: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
f210: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
f220: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
f230: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
f240: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
f250: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
f260: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
f270: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
f280: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
f290: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
f2a0: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
f2b0: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
f2c0: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
f2d0: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
f2e0: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
f2f0: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
f300: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
f310: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
f320: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
f330: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
f340: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
f350: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
f360: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
f370: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
f380: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
f390: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
f3a0: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
f3b0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
f3c0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
f3d0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
f3e0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
f3f0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
f400: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
f410: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
f420: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
f430: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
f440: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
f450: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
f460: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
f470: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
f480: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
f490: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
f4a0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
f4b0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
f4c0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
f4d0: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
f4e0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
f4f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f500: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f510: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
f520: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
f530: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
f540: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
f550: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
f560: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f570: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
f580: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
f590: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
f5a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f5b0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
f5c0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
f5d0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
f5e0: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
f5f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f600: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f610: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
f620: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
f630: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
f640: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
f650: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
f660: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
f670: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
f680: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
f690: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
f6a0: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
f6b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
f6c0: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
f6d0: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
f6e0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
f6f0: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
f700: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
f710: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
f720: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
f730: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
f740: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
f750: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
f760: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
f770: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
f780: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
f790: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
f7a0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
f7b0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
f7c0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
f7d0: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
f7e0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
f7f0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
f800: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
f810: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
f820: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
f830: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
f840: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
f850: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
f860: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
f870: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
f880: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
f890: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
f8a0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
f8b0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
f8c0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
f8d0: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
f8e0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
f8f0: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
f900: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
f910: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
f920: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
f930: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
f940: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
f950: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
f960: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
f970: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
f980: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
f990: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
f9a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f9b0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
f9c0: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
f9d0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
f9e0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
f9f0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
fa00: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
fa10: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
fa20: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
fa30: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
fa40: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
fa50: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
fa60: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
fa70: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
fa80: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
fa90: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
faa0: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
fab0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
fac0: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
fad0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
fae0: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
faf0: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
fb00: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
fb10: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
fb20: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
fb30: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
fb40: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
fb50: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
fb60: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
fb70: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
fb80: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
fb90: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
fba0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
fbb0: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
fbc0: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
fbd0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
fbe0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
fbf0: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
fc00: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
fc10: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
fc20: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
fc30: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
fc40: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
fc50: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
fc60: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
fc70: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
fc80: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
fc90: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
fca0: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
fcb0: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
fcc0: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
fcd0: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
fce0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
fcf0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
fd00: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
fd10: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
fd20: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
fd30: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
fd40: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
fd50: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
fd60: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
fd70: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
fd80: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
fd90: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
fda0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
fdb0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
fdc0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
fdd0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
fde0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
fdf0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
fe00: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
fe10: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
fe20: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
fe30: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
fe40: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
fe50: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
fe60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fe70: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
fe80: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
fe90: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
fea0: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
feb0: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
fec0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
fed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fee0: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
fef0: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
ff00: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
ff10: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
ff20: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
ff30: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
ff40: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
ff50: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
ff60: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
ff70: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
ff80: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
ff90: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
ffa0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
ffb0: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
ffc0: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
ffd0: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
ffe0: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
fff0: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
10000 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
10010 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
10020 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
10030 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
10040 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
10050 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
10060 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
10070 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
10080 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
10090 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
100a0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
100b0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
100c0 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
100d0 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
100e0 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
100f0 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
10100 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
10110 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
10120 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
10130 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72  iven on the corr
10140 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
10150 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
10160 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
10170 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
10180 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
10190 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
101a0 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
101b0 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
101c0 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
101d0 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
101e0 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
101f0 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
10200 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
10210 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
10220 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
10230 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
10240 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
10250 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
10260 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10270 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
10280 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10290 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
102a0 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
102b0 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
102c0 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
102d0 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
102e0 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
102f0 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
10300 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
10310 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
10320 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
10330 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
10340 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
10350 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
10360 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
10370 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
10380 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10390 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
103a0 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
103b0 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
103c0 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
103d0 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
103e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
103f0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
10400 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
10410 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
10420 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
10430 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
10440 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
10450 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
10460 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
10470 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
10480 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
10490 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
104a0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
104b0 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
104c0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
104d0 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
104e0 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
104f0 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
10500 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
10510 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
10520 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
10530 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
10540 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
10550 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
10560 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
10570 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
10580 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
10590 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
105a0 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
105b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
105c0 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
105d0 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
105e0 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
105f0 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
10600 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
10610 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10620 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
10630 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
10640 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
10650 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
10660 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
10670 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
10680 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
10690 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
106a0 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
106b0 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
106c0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
106d0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
106e0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
106f0 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
10700 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
10710 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
10720 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
10730 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
10740 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
10750 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
10760 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
10770 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
10780 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10790 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
107a0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
107b0 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
107c0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
107d0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
107e0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
107f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
10800 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10810 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
10820 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
10830 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10840 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
10850 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
10860 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
10870 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
10880 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
10890 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
108a0 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
108b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
108c0 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
108d0 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
108e0 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
108f0 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
10900 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
10910 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
10920 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
10930 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
10940 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
10950 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
10960 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
10970 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
10980 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
10990 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
109a0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
109b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
109c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
109d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
109e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
109f0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
10a00 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
10a10 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
10a20 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10a30 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
10a40 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
10a50 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
10a60 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
10a70 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
10a80 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
10a90 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
10aa0 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
10ab0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
10ac0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
10ad0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
10ae0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10af0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
10b00 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
10b10 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
10b20 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
10b30 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
10b40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
10b50 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
10b60 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
10b70 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10b80 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
10b90 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
10ba0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
10bb0 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
10bc0 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
10bd0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
10be0 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
10bf0 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
10c00 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
10c10 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
10c20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
10c30 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
10c40 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
10c50 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
10c60 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10c70 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
10c80 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
10c90 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
10ca0 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
10cb0 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
10cc0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
10cd0 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
10ce0 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
10cf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
10d00 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
10d10 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
10d20 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
10d30 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
10d40 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10d50 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
10d60 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
10d70 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
10d80 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
10d90 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
10da0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10db0 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
10dc0 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
10dd0 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
10de0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
10df0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
10e00 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
10e10 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
10e20 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
10e30 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
10e40 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
10e50 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10e60 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
10e70 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
10e80 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
10e90 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
10ea0 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
10eb0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
10ec0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
10ed0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10ee0 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
10ef0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
10f00 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
10f10 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
10f20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
10f30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
10f40 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
10f50 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
10f60 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
10f70 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
10f80 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
10f90 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
10fa0 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
10fb0 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
10fc0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
10fd0 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
10fe0 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
10ff0 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
11000 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
11010 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
11020 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
11030 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
11040 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
11050 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
11060 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
11070 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
11080 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
11090 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
110a0 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
110b0 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
110c0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
110d0 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
110e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
110f0 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
11100 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
11110 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
11120 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
11130 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
11140 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
11150 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
11160 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
11170 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11180 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
11190 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
111a0 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
111b0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
111c0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
111d0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
111e0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
111f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
11200 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
11210 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
11220 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
11230 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
11240 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
11250 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
11260 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
11270 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
11280 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
11290 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
112a0 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
112b0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
112c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
112d0 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
112e0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
112f0 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
11300 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
11310 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11320 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
11330 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
11340 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
11350 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11360 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
11370 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
11380 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
11390 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
113a0 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
113b0 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
113c0 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
113d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
113e0 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
113f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11400 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
11410 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
11420 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
11430 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
11440 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
11450 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
11460 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
11470 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
11480 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
11490 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
114a0 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
114b0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
114c0 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
114d0 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
114e0 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
114f0 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
11500 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
11510 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
11520 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
11530 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
11540 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
11550 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
11560 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
11570 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
11580 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
11590 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
115a0 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
115b0 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
115c0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68  eds..**.** <b>Th
115d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
115e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
115f0 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
11600 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
11610 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  ** must ensure t
11620 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
11630 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
11640 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
11650 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
11660 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
11670 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
11680 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  .</b>.**.** The 
11690 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
116a0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61   interface.** ma
116b0 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
116c0 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
116d0 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
116e0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
116f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11700 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
11710 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
11720 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
11730 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
11740 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
11750 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
11760 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
11770 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
11780 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
11790 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
117a0 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
117b0 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
117c0 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
117d0 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
117e0 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
117f0 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
11800 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
11810 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
11820 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
11830 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
11840 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11850 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
11860 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
11870 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
11880 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
11890 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
118a0 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
118b0 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
118c0 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
118d0 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
118e0 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
118f0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
11900 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11910 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
11920 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
11930 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
11940 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11950 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
11960 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
11970 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
11980 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
11990 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
119a0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
119b0 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
119c0 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
119d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
119e0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
119f0 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
11a00 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
11a10 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
11a20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
11a30 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
11a40 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  nections.** METH
11a50 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
11a60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
11a70 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
11a80 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
11a90 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
11aa0 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
11ab0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
11ac0 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
11ad0 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
11ae0 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
11af0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
11b00 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
11b10 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
11b20 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
11b30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
11b40 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
11b50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
11b60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
11b70 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
11b80 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
11b90 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
11ba0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
11bb0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
11bc0 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
11bd0 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
11be0 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
11bf0 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
11c00 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
11c10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11c20 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
11c30 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
11c40 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
11c50 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
11c60 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
11c70 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
11c80 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
11c90 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
11ca0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
11cb0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
11cc0 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
11cd0 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
11ce0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
11cf0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
11d00 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
11d10 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
11d20 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
11d30 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
11d40 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
11d50 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
11d60 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
11d70 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
11d80 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
11d90 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
11da0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
11db0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
11dc0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
11dd0 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
11de0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
11df0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
11e00 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
11e10 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11e20 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
11e30 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
11e40 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
11e50 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
11e60 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
11e70 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
11e80 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
11e90 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
11ea0 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
11eb0 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
11ec0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
11ed0 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
11ee0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
11ef0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
11f00 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
11f10 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
11f20 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
11f30 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
11f40 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
11f50 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
11f60 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
11f70 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
11f80 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
11f90 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
11fa0 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
11fb0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
11fc0 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
11fd0 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
11fe0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11ff0 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
12000 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
12010 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
12020 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
12030 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
12040 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
12050 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
12060 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
12070 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
12080 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
12090 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
120a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
120b0 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
120c0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
120d0 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
120e0 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
120f0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
12100 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
12110 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
12120 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
12130 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
12140 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
12150 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
12160 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
12170 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
12180 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
12190 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
121a0 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
121b0 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
121c0 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
121d0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
121e0 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
121f0 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
12200 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
12210 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
12220 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
12230 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
12240 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
12250 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
12260 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
12270 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
12280 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
12290 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
122a0 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
122b0 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
122c0 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
122d0 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
122e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
122f0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
12300 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
12310 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
12320 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
12330 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
12340 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
12350 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
12360 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
12370 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
12380 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
12390 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
123a0 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
123b0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
123c0 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
123d0 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
123e0 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
123f0 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
12400 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
12410 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
12420 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
12430 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
12440 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
12450 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
12460 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
12470 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
12480 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
12490 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
124a0 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
124b0 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
124c0 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
124d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
124e0 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
124f0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
12500 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
12510 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
12520 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
12530 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
12540 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
12550 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
12560 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
12570 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
12580 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
12590 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
125a0 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a    For example,.*
125b0 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
125c0 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
125d0 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
125e0 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
125f0 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
12600 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
12610 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
12620 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
12630 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
12640 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
12650 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
12660 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
12670 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
12680 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
12690 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
126a0 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
126b0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
126c0 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
126d0 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
126e0 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
126f0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
12700 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
12710 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
12720 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
12730 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
12740 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
12750 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
12760 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
12770 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
12780 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
12790 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
127a0 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
127b0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
127c0 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
127d0 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
127e0 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
127f0 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
12800 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
12810 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
12820 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
12830 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12840 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
12850 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
12860 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
12870 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
12880 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
12890 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
128a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
128b0 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
128c0 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
128d0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
128e0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
128f0 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
12900 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
12910 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
12920 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
12930 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
12940 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
12950 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
12960 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
12970 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
12980 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
12990 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
129a0 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
129b0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
129c0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
129d0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
129e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
129f0 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
12a00 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12a10 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
12a20 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
12a30 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
12a40 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
12a50 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
12a60 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
12a70 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
12a80 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
12a90 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
12aa0 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
12ab0 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
12ac0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
12ad0 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
12ae0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
12af0 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
12b00 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
12b10 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
12b20 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
12b30 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
12b40 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
12b50 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
12b60 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
12b70 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
12b80 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
12b90 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
12ba0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
12bb0 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
12bc0 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
12bd0 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
12be0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
12bf0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
12c00 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
12c10 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
12c20 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
12c30 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
12c40 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
12c50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
12c60 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20  tion Options.** 
12c70 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69  KEYWORDS: {confi
12c80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d  guration option}
12c90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
12ca0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
12cb0 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
12cc0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12cd0 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
12ce0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
12cf0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
12d00 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
12d10 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
12d20 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
12d30 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
12d40 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
12d50 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
12d60 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
12d70 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
12d80 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12d90 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
12da0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
12db0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
12dc0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
12dd0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
12de0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12df0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
12e00 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
12e10 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
12e20 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12e30 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
12e40 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
12e50 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
12e60 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
12e70 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
12e80 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
12e90 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
12ea0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
12eb0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12ec0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
12ed0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12ee0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
12ef0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12f00 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12f10 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12f20 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12f30 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12f40 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12f50 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
12f60 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
12f70 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
12f80 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
12f90 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
12fa0 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
12fb0 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
12fc0 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
12fd0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
12fe0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12ff0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13000 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13010 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13020 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13030 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13040 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
13050 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
13060 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
13070 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
13080 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
13090 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
130a0 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
130b0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
130c0 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
130d0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
130e0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
130f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
13100 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
13110 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13120 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
13130 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13140 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74  ULTITHREAD]] <dt
13150 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13160 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
13170 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
13180 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
13190 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
131a0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
131b0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
131c0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
131d0 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
131e0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
131f0 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
13200 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
13210 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
13220 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13230 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
13240 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
13250 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
13260 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
13270 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
13280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13290 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
132a0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
132b0 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
132c0 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
132d0 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
132e0 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
132f0 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
13300 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
13310 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
13320 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
13330 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
13340 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
13350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13360 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
13370 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
13380 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13390 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
133a0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
133b0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
133c0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
133d0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
133e0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
133f0 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
13400 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
13410 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
13420 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13430 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
13440 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
13450 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
13460 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
13470 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
13480 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13490 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
134a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
134b0 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74  SERIALIZED]] <dt
134c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
134d0 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
134e0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
134f0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
13500 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
13510 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
13520 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
13530 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
13540 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
13550 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
13560 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
13570 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
13580 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
13590 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
135a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
135b0 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
135c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
135d0 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
135e0 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
135f0 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
13600 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
13610 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
13620 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13630 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
13640 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
13650 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
13660 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
13670 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
13680 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13690 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
136a0 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
136b0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
136c0 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
136d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
136e0 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
136f0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
13700 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
13710 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
13720 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
13730 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
13740 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13750 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13760 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13770 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13780 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13790 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
137a0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
137b0 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
137c0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
137d0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
137e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
137f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
13800 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
13810 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
13820 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13830 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
13840 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
13850 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13860 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
13870 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
13880 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
13890 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
138a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
138b0 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
138c0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
138d0 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
138e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
138f0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13900 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
13910 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13920 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
13930 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
13940 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
13950 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
13960 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
13970 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
13980 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
13990 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
139a0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
139b0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
139c0 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
139d0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
139e0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
139f0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
13a00 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
13a10 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
13a20 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
13a30 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
13a40 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
13a50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13a60 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
13a70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13a80 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
13a90 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13aa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13ab0 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
13ac0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13ad0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
13ae0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13af0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13b00 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
13b10 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
13b20 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  e..** The [sqlit
13b30 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
13b40 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
13b50 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
13b60 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
13b70 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
13b80 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
13b90 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
13ba0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
13bb0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
13bc0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
13bd0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
13be0 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
13bf0 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
13c00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13c10 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
13c20 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
13c30 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
13c40 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
13c50 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13c60 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53  EMSTATUS]] <dt>S
13c70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13c80 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
13c90 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13ca0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
13cb0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
13cc0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
13cd0 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e   type int,.** in
13ce0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
13cf0 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
13d00 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
13d10 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
13d20 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c   of.** memory al
13d30 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
13d40 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
13d50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
13d60 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20  atistics are.** 
13d70 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f  disabled, the fo
13d80 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
13d90 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
13da0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
13db0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
13dc0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
13dd0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
13de0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
13df0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
13e00 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
13e10 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
13e20 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
13e30 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
13e40 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20  status64()].**  
13e50 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
13e60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
13e70 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
13e80 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
13e90 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
13ea0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
13eb0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
13ec0 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
13ed0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
13ee0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
13ef0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
13f00 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
13f10 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
13f20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13f30 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
13f40 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13f50 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
13f60 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
13f70 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13f80 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  H option specifi
13f90 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
13fa0 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  ry buffer.** tha
13fb0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
13fc0 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d   for scratch mem
13fd0 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72  ory.  ^(There ar
13fe0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13ff0 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43  s.** to SQLITE_C
14000 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20  ONFIG_SCRATCH:  
14010 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
14020 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
14030 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
14040 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
14050 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
14060 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
14070 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
14080 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
14090 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
140a0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
140b0 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
140c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
140d0 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .)^.** The first
140e0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
140f0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
14100 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
14110 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
14120 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
14130 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
14140 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74  ^SQLite will not
14150 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f   use more than o
14160 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ne scratch buffe
14170 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a  rs per thread..*
14180 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
14190 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73  ever request a s
141a0 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
141b0 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
141c0 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
141d0 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
141e0 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
141f0 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
14200 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
14210 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
14220 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
14230 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
14240 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
14250 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
14260 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
14270 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
14280 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
14290 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65  eded.<p>.** ^Whe
142a0 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  n the applicatio
142b0 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61  n provides any a
142c0 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68  mount of scratch
142d0 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a   memory using.**
142e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
142f0 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61  CRATCH, SQLite a
14300 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72  voids unnecessar
14310 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69  y large.** [sqli
14320 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20  te3_malloc|heap 
14330 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a  allocations]..**
14340 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b   This can help [
14350 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65  Robson proof|pre
14360 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  vent memory allo
14370 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d  cation failures]
14380 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20   due to heap.** 
14390 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  fragmentation in
143a0 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65   low-memory embe
143b0 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  dded systems..**
143c0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
143d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
143e0 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c  ECACHE]] <dt>SQL
143f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14400 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
14410 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
14420 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f  NFIG_PAGECACHE o
14430 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
14440 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a  a memory pool.**
14450 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
14460 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74   use for the dat
14470 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
14480 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
14490 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  t page.** cache 
144a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
144b0 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
144c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
144d0 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20  s a no-op if an 
144e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
144f0 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
14500 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
14510 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
14520 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
14530 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20  IG_PCACHE2]..** 
14540 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
14550 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
14560 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14570 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72  CACHE: A pointer
14580 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c   to.** 8-byte al
14590 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d  igned memory (pM
145a0 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  em), the size of
145b0 20 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65   each page cache
145c0 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61   line (sz),.** a
145d0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
145e0 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29   cache lines (N)
145f0 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
14600 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
14610 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
14620 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
14630 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
14640 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
14650 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70  512 and 65536) p
14660 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62  lus some extra b
14670 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ytes for each.**
14680 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
14690 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  The number of ex
146a0 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64  tra bytes needed
146b0 20 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61   by the page hea
146c0 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65  der.** can be de
146d0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b  termined using [
146e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
146f0 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20  ACHE_HDRSZ]..** 
14700 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
14710 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
14720 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
14730 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
14740 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
14750 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
14760 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a  ry.  The pMem.**
14770 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
14780 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  e either a NULL 
14790 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69  pointer or a poi
147a0 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
147b0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f  e.** aligned blo
147c0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20  ck of memory of 
147d0 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
147e0 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a  tes, otherwise.*
147f0 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  * subsequent beh
14800 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
14810 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65  ed..** ^When pMe
14820 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  m is not NULL, S
14830 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76  QLite will striv
14840 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d  e to use the mem
14850 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ory provided.** 
14860 74 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20  to satisfy page 
14870 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c  cache needs, fal
14880 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71  ling back to [sq
14890 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
148a0 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63  if.** a page cac
148b0 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65  he line is large
148c0 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20  r than sz bytes 
148d0 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65  or if all of the
148e0 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20   pMem buffer.** 
148f0 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a  is exhausted..**
14900 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c   ^If pMem is NUL
14910 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a  L and N is non-z
14920 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64  ero, then each d
14930 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14940 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e  on.** does an in
14950 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63  itial bulk alloc
14960 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63  ation for page c
14970 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66  ache memory.** f
14980 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
14990 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e  loc()] sufficien
149a0 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69  t for N cache li
149b0 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69  nes if N is posi
149c0 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31  tive or.** of -1
149d0 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e  024*N bytes if N
149e0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20   is negative, . 
149f0 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
14a00 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
14a10 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
14a20 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
14a30 76 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69  vided by the ini
14a40 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  tial.** allocati
14a50 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  on, then SQLite 
14a60 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
14a70 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72  _malloc()] separ
14a80 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a  ately for each.*
14a90 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63  * additional cac
14aa0 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a  he line. </dd>.*
14ab0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14ac0 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
14ad0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14ae0 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
14af0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14b00 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73  IG_HEAP option s
14b10 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
14b20 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
14b30 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
14b40 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c  will use for all
14b50 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
14b60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14b70 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e  n needs.** beyon
14b80 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
14b90 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
14ba0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
14bb0 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  and.** [SQLITE_C
14bc0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
14bd0 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
14be0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
14bf0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14c00 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
14c10 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
14c20 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
14c30 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
14c40 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
14c50 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
14c60 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
14c70 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
14c80 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
14c90 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
14ca0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
14cb0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
14cc0 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
14cd0 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
14ce0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
14cf0 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
14d00 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
14d10 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
14d20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
14d30 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
14d40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
14d50 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
14d60 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
14d70 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
14d80 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
14d90 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
14da0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
14db0 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
14dc0 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
14dd0 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
14de0 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
14df0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
14e00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14e10 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
14e20 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
14e30 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
14e40 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
14e50 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
14e60 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
14e70 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
14e80 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
14e90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
14ea0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
14eb0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
14ec0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
14ed0 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
14ee0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
14ef0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
14f00 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
14f10 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
14f20 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
14f30 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14f40 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
14f50 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
14f60 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
14f70 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
14f80 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
14f90 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
14fa0 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
14fb0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14fc0 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
14fd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14fe0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
14ff0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15000 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
15010 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15020 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15030 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
15040 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
15050 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15060 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15070 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
15080 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
15090 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
150a0 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
150b0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
150c0 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
150d0 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
150e0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
150f0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
15100 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
15110 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
15120 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15130 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15140 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
15150 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
15160 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15170 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
15180 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15190 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
151a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
151b0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
151c0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
151d0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
151e0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
151f0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
15200 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
15210 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
15220 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
15230 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
15240 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
15250 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15260 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15270 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
15280 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
15290 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
152a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
152b0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
152c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
152d0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
152e0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
152f0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
15300 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15310 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
15320 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
15330 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
15340 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
15350 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15360 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
15370 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
15380 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
15390 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
153a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
153b0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
153c0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
153d0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
153e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
153f0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
15400 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
15410 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
15420 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
15430 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
15440 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
15450 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
15460 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
15470 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
15480 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
15490 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
154a0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
154b0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
154c0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
154d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
154e0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
154f0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
15500 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
15510 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
15520 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
15530 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
15540 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
15550 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
15560 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
15570 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15580 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15590 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
155a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
155b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
155c0 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
155d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
155e0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
155f0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15600 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
15610 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
15620 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
15630 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
15640 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
15650 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15660 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
15670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
15680 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
15690 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
156a0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
156b0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
156c0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
156d0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
156e0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
156f0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
15700 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15710 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
15720 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
15730 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
15740 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
15750 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
15760 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15770 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
15780 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
15790 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
157a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
157b0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
157c0 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
157d0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
157e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
157f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15800 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15810 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
15820 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
15830 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15840 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15850 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
15860 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15870 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15880 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
15890 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
158a0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
158b0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
158c0 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
158d0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
158e0 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
158f0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
15900 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
15910 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
15920 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15930 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
15940 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
15950 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15960 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
15970 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15980 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
15990 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
159a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
159b0 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
159c0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
159d0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
159e0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
159f0 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
15a00 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
15a10 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
15a20 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
15a30 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
15a40 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15a50 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
15a60 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
15a70 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15a80 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
15a90 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
15aa0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
15ab0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15ac0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
15ad0 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
15ae0 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
15af0 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
15b00 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
15b10 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
15b20 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
15b30 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
15b40 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
15b50 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
15b60 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
15b70 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
15b80 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
15b90 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
15ba0 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
15bb0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
15bc0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
15bd0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
15be0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
15bf0 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
15c00 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
15c10 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
15c20 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
15c30 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
15c40 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
15c50 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
15c60 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
15c70 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
15c80 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15c90 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
15ca0 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
15cb0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
15cc0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15cd0 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
15ce0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
15cf0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
15d00 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
15d10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
15d20 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
15d30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
15d40 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
15d50 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
15d60 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
15d70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
15d80 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
15d90 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
15da0 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
15db0 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
15dc0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
15dd0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
15de0 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
15df0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15e00 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
15e10 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
15e20 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
15e30 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
15e40 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15e50 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
15e60 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
15e70 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
15e80 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
15e90 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
15ea0 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
15eb0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
15ec0 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
15ed0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
15ee0 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
15ef0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
15f00 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
15f10 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
15f20 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
15f30 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
15f40 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
15f50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15f60 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
15f70 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
15f80 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
15f90 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
15fa0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15fb0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
15fc0 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
15fd0 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
15fe0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
15ff0 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
16000 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
16010 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
16020 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
16030 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
16040 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
16050 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16060 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
16070 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
16080 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
16090 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
160a0 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
160b0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
160c0 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
160d0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
160e0 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
160f0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
16100 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
16110 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
16120 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
16130 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
16140 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
16150 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
16160 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
16170 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
16180 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
16190 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
161a0 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
161b0 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
161c0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
161d0 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
161e0 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
161f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
16200 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
16210 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
16220 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16230 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
16240 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
16250 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
16260 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
16270 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
16280 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
16290 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
162a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
162b0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
162c0 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
162d0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
162e0 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
162f0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16300 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
16310 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
16320 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16330 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
16340 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
16350 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
16360 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
16370 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
16380 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
16390 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
163a0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
163b0 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
163c0 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
163d0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
163e0 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
163f0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
16400 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
16410 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
16420 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
16430 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
16440 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
16450 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16460 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
16470 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
16480 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
16490 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
164a0 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
164b0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
164c0 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
164d0 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
164e0 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
164f0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
16500 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
16510 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
16520 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
16530 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
16540 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
16550 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
16560 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
16570 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
16580 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
16590 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
165a0 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
165b0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
165c0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
165d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
165e0 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
165f0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
16600 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16610 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
16620 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16630 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
16640 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
16650 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
16660 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
16670 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
16680 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
16690 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
166a0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
166b0 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
166c0 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
166d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
166e0 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
166f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16700 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
16710 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
16720 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
16730 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
16740 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
16750 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
16760 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
16770 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
16780 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
16790 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
167a0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
167b0 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
167c0 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
167d0 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
167e0 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
167f0 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
16800 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
16810 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
16820 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
16830 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
16840 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
16850 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
16860 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
16870 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
16880 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
16890 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
168a0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
168b0 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
168c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
168d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
168e0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
168f0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
16900 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
16910 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
16920 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
16930 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
16940 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
16950 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
16960 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
16970 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
16980 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
16990 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
169a0 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
169b0 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
169c0 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
169d0 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
169e0 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
169f0 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
16a00 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
16a10 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
16a20 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
16a30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
16a40 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
16a50 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
16a60 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
16a70 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
16a80 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
16a90 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
16aa0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16ab0 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
16ac0 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
16ad0 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
16ae0 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
16af0 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
16b00 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
16b10 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16b20 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
16b30 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16b40 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
16b50 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
16b60 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
16b70 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
16b80 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
16b90 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
16ba0 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
16bb0 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
16bc0 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
16bd0 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
16be0 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
16bf0 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
16c00 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16c10 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
16c20 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
16c30 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
16c40 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
16c50 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
16c60 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
16c70 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
16c80 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
16c90 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
16ca0 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
16cb0 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
16cc0 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
16cd0 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
16ce0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
16cf0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
16d00 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
16d10 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
16d20 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
16d30 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
16d40 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
16d50 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
16d60 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
16d70 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
16d80 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16d90 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
16da0 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
16db0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
16dc0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
16dd0 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
16de0 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
16df0 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
16e00 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
16e10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16e20 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
16e30 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16e40 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16e50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
16e60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
16e70 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
16e80 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
16e90 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
16ea0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
16eb0 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
16ec0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
16ed0 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
16ee0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
16ef0 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
16f00 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16f10 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
16f20 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
16f30 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
16f40 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
16f50 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
16f60 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
16f70 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
16f80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16f90 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
16fa0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16fb0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
16fc0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
16fd0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
16fe0 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
16ff0 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
17000 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
17010 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17020 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
17030 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
17040 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
17050 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
17060 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
17070 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
17080 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
17090 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
170a0 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
170b0 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
170c0 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
170d0 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
170e0 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
170f0 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
17100 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
17110 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
17120 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
17130 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17140 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
17150 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17160 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
17170 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
17180 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
17190 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
171a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
171b0 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
171c0 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
171d0 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
171e0 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
171f0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
17200 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
17210 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
17220 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
17230 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
17240 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
17250 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
17260 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
17270 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
17280 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
17290 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
172a0 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
172b0 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
172c0 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
172d0 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
172e0 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
172f0 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
17300 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
17310 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
17320 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
17330 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
17340 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
17350 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
17360 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b  s value..**.** [
17370 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
17380 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a  TMTJRNL_SPILL]].
17390 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
173a0 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
173b0 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ILL.** <dd>^The 
173c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
173d0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74  MTJRNL_SPILL opt
173e0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
173f0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17400 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68  ch.** becomes th
17410 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  e [statement jou
17420 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64  rnal] spill-to-d
17430 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20  isk threshold.  
17440 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a  .** [Statement j
17450 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c  ournals] are hel
17460 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69  d in memory unti
17470 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e  l their size (in
17480 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65   bytes).** excee
17490 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c  ds this threshol
174a0 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e  d, at which poin
174b0 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74  t they are writt
174c0 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f  en to disk..** O
174d0 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f  r if the thresho
174e0 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d  ld is -1, statem
174f0 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65  ent journals are
17500 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20   always held.** 
17510 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d  exclusively in m
17520 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20  emory..** Since 
17530 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a  many statement j
17540 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65  ournals never be
17550 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74  come large, sett
17560 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a  ing the spill.**
17570 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20   threshold to a 
17580 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34  value such as 64
17590 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20  KiB can greatly 
175a0 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e  reduce the amoun
175b0 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75  t of.** I/O requ
175c0 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ired to support 
175d0 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61  statement rollba
175e0 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ck..** The defau
175f0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  lt value for thi
17600 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e  s setting is con
17610 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a  trolled by the.*
17620 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52  * [SQLITE_STMTJR
17630 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c  NL_SPILL] compil
17640 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
17650 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
17660 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17670 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
17680 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
17690 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
176a0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
176b0 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
176c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
176d0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
176e0 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
176f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17700 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
17710 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
17720 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
17730 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17740 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
17750 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
17760 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
17770 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17780 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
17790 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
177a0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
177b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
177c0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
177d0 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
177e0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
177f0 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
17800 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
17810 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
17820 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
17830 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
17840 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17850 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
17860 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
17870 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17880 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
17890 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
178a0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
178b0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
178c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
178d0 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
178e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
178f0 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
17900 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
17910 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
17920 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
17930 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
17940 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17950 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
17960 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
17970 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17980 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
17990 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
179a0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
179b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
179c0 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
179d0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
179e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
179f0 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
17a00 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
17a10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17a20 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
17a30 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
17a40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17a50 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
17a60 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
17a70 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
17a80 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
17a90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
17aa0 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
17ab0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
17ac0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
17ad0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17ae0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
17af0 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
17b00 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
17b10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
17b20 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
17b30 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
17b40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17b50 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
17b60 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c  ZE    22  /* sql
17b70 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69  ite3_int64, sqli
17b80 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65  te3_int64 */.#de
17b90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17ba0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
17bb0 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e  E      23  /* in
17bc0 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
17bd0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17be0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20  _PCACHE_HDRSZ   
17bf0 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20       24  /* int 
17c00 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  *psz */.#define 
17c10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
17c20 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20  ASZ             
17c30 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65    25  /* unsigne
17c40 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23  d int szPma */.#
17c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17c60 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
17c70 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20  ILL      26  /* 
17c80 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a  int nByte */../*
17c90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
17ca0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
17cb0 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
17cc0 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
17cd0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
17ce0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
17cf0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
17d00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
17d10 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
17d20 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
17d30 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
17d40 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
17d50 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
17d60 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
17d70 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17d80 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
17d90 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
17da0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
17db0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
17dc0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17dd0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
17de0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
17df0 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
17e00 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
17e10 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
17e20 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17e30 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
17e40 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
17e50 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
17e60 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
17e70 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
17e80 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
17e90 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
17ea0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
17eb0 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
17ec0 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
17ed0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
17ee0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
17ef0 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
17f00 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
17f10 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
17f20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
17f30 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
17f40 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
17f50 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
17f60 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
17f70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
17f80 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
17f90 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
17fa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
17fb0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
17fc0 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
17fd0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
17fe0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17ff0 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
18000 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
18010 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
18020 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
18030 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
18040 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
18050 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
18060 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18070 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
18080 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
18090 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
180a0 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
180b0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
180c0 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
180d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
180e0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
180f0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
18100 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
18110 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
18120 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
18130 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
18140 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
18150 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
18160 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
18170 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18180 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
18190 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
181a0 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
181b0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
181c0 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
181d0 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
181e0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
181f0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
18200 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
18210 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18220 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
18230 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18240 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
18250 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
18260 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
18270 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
18280 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
18290 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
182a0 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
182b0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
182c0 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
182d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
182e0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
182f0 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
18300 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
18310 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
18320 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
18330 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
18340 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
18350 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
18360 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
18370 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
18380 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
18390 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
183a0 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
183b0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
183c0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
183d0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
183e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
183f0 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
18400 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
18410 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
18420 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
18430 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
18440 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
18450 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
18460 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18470 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
18480 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
18490 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
184a0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
184b0 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
184c0 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
184d0 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
184e0 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
184f0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
18500 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
18510 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
18520 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
18530 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
18540 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
18550 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
18560 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
18570 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
18580 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
18590 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
185a0 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
185b0 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
185c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
185d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
185e0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
185f0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18600 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18610 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
18620 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
18630 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
18640 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
18650 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18660 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
18670 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
18680 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
18690 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
186a0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
186b0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
186c0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
186d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
186e0 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
186f0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
18700 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18710 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18720 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
18730 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
18740 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
18750 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18760 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
18770 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18780 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18790 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
187a0 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
187b0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
187c0 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
187d0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
187e0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
187f0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
18800 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18810 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18820 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
18830 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
18840 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
18850 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
18860 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
18870 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
18880 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
18890 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
188a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
188b0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
188c0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
188d0 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
188e0 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
188f0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
18900 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
18910 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18920 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
18930 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a  OKENIZER</dt>.**
18940 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18950 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
18960 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
18970 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74  the two-argument
18980 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  .** version of t
18990 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  he [fts3_tokeniz
189a0 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77  er()] function w
189b0 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20  hich is part of 
189c0 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75  the.** [FTS3] fu
189d0 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65  ll-text search e
189e0 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e  ngine extension.
189f0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18a00 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18a10 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18a20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18a30 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
18a40 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
18a50 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b  disable fts3_tok
18a60 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70  enizer() or.** p
18a70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
18a80 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
18a90 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  () or negative t
18aa0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
18ab0 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ing.** unchanged
18ac0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
18ad0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
18ae0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18af0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18b00 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18b10 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18b20 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f   whether fts3_to
18b30 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62  kenizer is disab
18b40 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
18b50 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
18b60 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
18b70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
18b80 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
18b90 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
18ba0 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74  case the new set
18bb0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
18bc0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
18bd0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18be0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18bf0 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
18c00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18c10 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18c20 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18c30 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c  disable the [sql
18c40 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
18c50 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ion()].** interf
18c60 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c  ace independentl
18c70 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65  y of the [load_e
18c80 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20  xtension()] SQL 
18c90 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
18ca0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
18cb0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18cc0 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f  )] API enables o
18cd0 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20  r disables both 
18ce0 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71  the.** C-API [sq
18cf0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
18d00 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20  sion()] and the 
18d10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f  SQL function [lo
18d20 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e  ad_extension()].
18d30 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18d40 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18d50 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18d60 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20   When the first 
18d70 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
18d80 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c   interface is 1,
18d90 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43   then only the C
18da0 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c  -API is.** enabl
18db0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  ed and the SQL f
18dc0 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20  unction remains 
18dd0 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68  disabled.  If th
18de0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18df0 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65   to.** this inte
18e00 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e  rface is 0, then
18e10 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20   both the C-API 
18e20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
18e30 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65  tion are disable
18e40 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  d..** If the fir
18e50 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d  st argument is -
18e60 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67  1, then no chang
18e70 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73  es are made to s
18e80 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74  tate of either t
18e90 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74  he.** C-API or t
18ea0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
18eb0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
18ec0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
18ed0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
18ee0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
18ef0 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
18f00 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18f10 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33  whether [sqlite3
18f20 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18f30 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
18f40 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
18f50 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67  nabled following
18f60 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
18f70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18f80 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55  r may.** be a NU
18f90 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77  LL pointer, in w
18fa0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
18fb0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
18fc0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a   reported back..
18fd0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
18fe0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18ff0 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64  IG_MAINDBNAME</d
19000 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
19010 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
19020 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61  to change the na
19030 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22  me of the "main"
19040 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68   database.** sch
19050 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20  ema.  ^The sole 
19060 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
19070 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74  inter to a const
19080 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a  ant UTF8 string.
19090 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
190a0 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68  come the new sch
190b0 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63  ema name in plac
190c0 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53  e of "main".  ^S
190d0 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  QLite.** does no
190e0 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  t make a copy of
190f0 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63   the new main sc
19100 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67  hema name string
19110 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61  , so the applica
19120 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
19130 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67  ure that the arg
19140 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74  ument passed int
19150 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20  o this DBCONFIG 
19160 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e  option is unchan
19170 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74  ged.** until aft
19180 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  er the database 
19190 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
191a0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
191b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
191c0 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e  ONFIG_NO_CKPT_ON
191d0 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
191e0 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65  dd> Usually, whe
191f0 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20  n a database in 
19200 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73  wal mode is clos
19210 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66  ed or detached f
19220 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61  rom a .** databa
19230 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74  se handle, SQLit
19240 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73  e checks if this
19250 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20   will mean that 
19260 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f  there are now no
19270 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   .** connections
19280 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64   at all to the d
19290 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20  atabase. If so, 
192a0 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68  it performs a ch
192b0 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65  eckpoint .** ope
192c0 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c  ration before cl
192d0 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63  osing the connec
192e0 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f  tion. This optio
192f0 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  n may be used to
19300 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69  .** override thi
19310 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65  s behaviour. The
19320 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19330 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
19340 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  operation.** is 
19350 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e  an integer - non
19360 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65  -zero to disable
19370 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
19380 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28  close, or zero (
19390 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20  the.** default) 
193a0 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20  to enable them. 
193b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
193c0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
193d0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  r to an integer.
193e0 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  ** into which is
193f0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
19400 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
19410 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  her checkpoints-
19420 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65  on-close.** have
19430 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d   been disabled -
19440 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e   0 if they are n
19450 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
19460 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c  f they are..** <
19470 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
19480 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
19490 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
194a0 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  DBNAME          
194b0 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20    1000 /* const 
194c0 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  char* */.#define
194d0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
194e0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
194f0 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76         1001 /* v
19500 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
19510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19520 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
19530 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30  KEY           10
19540 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  02 /* int int* *
19550 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19560 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19570 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
19580 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1003 /* int int*
19590 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
195a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
195b0 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
195c0 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e  R 1004 /* int in
195d0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
195e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
195f0 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
19600 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20  ION 1005 /* int 
19610 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
19620 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19630 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
19640 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e        1006 /* in
19650 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
19660 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
19670 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
19680 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
19690 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
196a0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
196b0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
196c0 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
196d0 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
196e0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
196f0 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
19700 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
19710 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
19720 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
19730 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
19740 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
19750 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
19760 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
19770 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
19780 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
19790 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
197a0 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
197b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
197c0 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
197d0 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
197e0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
197f0 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
19800 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
19810 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
19820 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
19830 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
19840 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
19850 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
19860 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
19870 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
19880 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
19890 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
198a0 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
198b0 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
198c0 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
198d0 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
198e0 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
198f0 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
19900 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
19910 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
19920 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
19930 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
19940 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
19950 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
19960 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
19970 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
19980 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
19990 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
199a0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
199b0 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
199c0 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73   usually returns
199d0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a   the [rowid] of.
199e0 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ** the most rece
199f0 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
19a00 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
19a10 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
19a20 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
19a30 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
19a40 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72  ection D. ^Inser
19a50 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
19a60 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
19a70 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64  re not.** record
19a80 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  ed. ^If no succe
19a90 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
19aa0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
19ab0 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  s have ever occu
19ac0 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20  rred .** on the 
19ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19ae0 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69  ion D, then sqli
19af0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
19b00 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
19b10 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a   .** zero..**.**
19b20 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e   As well as bein
19b30 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61  g set automatica
19b40 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20  lly as rows are 
19b50 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61  inserted into da
19b60 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73  tabase.** tables
19b70 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
19b80 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
19b90 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74  ction may be set
19ba0 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a   explicitly by.*
19bb0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  * [sqlite3_set_l
19bc0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19bd0 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76  ()].**.** Some v
19be0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
19bf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
19c00 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74   INSERT rows int
19c10 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61  o rowid tables a
19c20 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d  s.** part of com
19c30 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61  mitting a transa
19c40 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66  ction (e.g. to f
19c50 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75  lush data accumu
19c60 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  lated in memory.
19c70 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20  ** to disk). In 
19c80 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71  this case subseq
19c90 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68  uent calls to th
19ca0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
19cb0 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20  rn the rowid.** 
19cc0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
19cd0 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49  these internal I
19ce0 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73  NSERT operations
19cf0 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f  , which leads to
19d00 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65   .** unintuitive
19d10 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61   results. Virtua
19d20 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
19d30 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20  tations that do 
19d40 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a  write to rowid.*
19d50 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73  * tables in this
19d60 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74   way can avoid t
19d70 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72  his problem by r
19d80 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69  estoring the ori
19d90 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20  ginal .** rowid 
19da0 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c  value using [sql
19db0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
19dc0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65  sert_rowid()] be
19dd0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a  fore returning .
19de0 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68  ** control to th
19df0 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e user..**.** ^(
19e00 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
19e10 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
19e20 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73  rigger then this
19e30 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a   routine will .*
19e40 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  * return the [ro
19e50 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
19e60 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67  rted row as long
19e70 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
19e80 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20  is .** running. 
19e90 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  Once the trigger
19ea0 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74   program ends, t
19eb0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19ec0 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
19ed0 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
19ee0 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
19ef0 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
19f00 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  was fired.)^.**.
19f10 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
19f20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
19f30 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
19f40 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
19f50 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
19f60 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
19f70 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
19f80 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
19f90 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
19fa0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
19fb0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
19fc0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
19fd0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
19fe0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
19ff0 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
1a000 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
1a010 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1a020 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
1a030 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
1a040 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
1a050 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
1a060 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
1a070 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
1a080 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
1a090 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
1a0a0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
1a0b0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
1a0c0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
1a0d0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
1a0e0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
1a0f0 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
1a100 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1a110 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
1a120 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
1a130 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1a140 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
1a150 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
1a160 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
1a170 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
1a180 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
1a190 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
1a1a0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
1a1b0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
1a1c0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
1a1d0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
1a1e0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
1a1f0 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
1a200 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
1a210 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a220 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1a230 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1a240 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
1a250 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
1a260 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
1a270 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1a280 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
1a290 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
1a2a0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1a2b0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
1a2c0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
1a2d0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
1a2e0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
1a2f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
1a300 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
1a310 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1a320 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
1a330 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
1a340 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
1a350 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
1a360 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
1a370 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1a380 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
1a390 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
1a3a0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a3b0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1a3c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1a3d0 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74   the Last Insert
1a3e0 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a   Rowid value..**
1a3f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1a400 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1a410 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
1a420 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d  rt_rowid(D, R) m
1a430 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65  ethod allows the
1a440 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
1a450 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65  ** set the value
1a460 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c   returned by cal
1a470 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73  ling sqlite3_las
1a480 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1a490 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f  ) to R .** witho
1a4a0 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72  ut inserting a r
1a4b0 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  ow into the data
1a4c0 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  base..*/.void sq
1a4d0 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
1a4e0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
1a4f0 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  te3*,sqlite3_int
1a500 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
1a510 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
1a520 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
1a530 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
1a540 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1a550 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1a560 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1a570 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
1a580 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
1a590 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
1a5a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
1a5b0 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
1a5c0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1a5d0 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
1a5e0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
1a5f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
1a600 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
1a610 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
1a620 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
1a630 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
1a640 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
1a650 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
1a660 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1a670 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
1a680 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
1a690 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
1a6a0 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
1a6b0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1a6c0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
1a6d0 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
1a6e0 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
1a6f0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
1a700 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
1a710 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
1a720 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
1a730 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
1a740 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
1a750 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
1a760 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
1a770 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
1a780 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1a790 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
1a7a0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1a7b0 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
1a7c0 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
1a7d0 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
1a7e0 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
1a7f0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
1a800 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
1a810 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
1a820 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
1a830 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
1a840 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
1a850 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
1a860 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
1a870 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
1a880 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
1a890 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
1a8a0 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
1a8b0 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
1a8c0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
1a8d0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
1a8e0 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
1a8f0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
1a900 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
1a910 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
1a920 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
1a930 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
1a940 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
1a950 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
1a960 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1a970 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
1a980 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1a990 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
1a9a0 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
1a9b0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
1a9c0 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
1a9d0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1a9e0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a9f0 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
1aa00 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1aa10 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
1aa20 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
1aa30 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1aa40 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
1aa50 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
1aa60 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
1aa70 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
1aa80 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
1aa90 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
1aaa0 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
1aab0 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
1aac0 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
1aad0 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
1aae0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1aaf0 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
1ab00 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
1ab10 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
1ab20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
1ab30 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
1ab40 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
1ab50 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
1ab60 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
1ab70 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
1ab80 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
1ab90 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
1aba0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
1abb0 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
1abc0 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
1abd0 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
1abe0 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
1abf0 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
1ac00 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
1ac10 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
1ac20 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
1ac30 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
1ac40 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
1ac50 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1ac60 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1ac70 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1ac80 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
1ac90 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
1aca0 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
1acb0 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
1acc0 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
1acd0 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
1ace0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1acf0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
1ad00 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
1ad10 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
1ad20 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
1ad30 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
1ad40 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
1ad50 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1ad60 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
1ad70 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
1ad80 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1ad90 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1ada0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
1adb0 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
1adc0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
1add0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
1ade0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1adf0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1ae00 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1ae10 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1ae20 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1ae30 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1ae40 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1ae50 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1ae60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ae70 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1ae80 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1ae90 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1aea0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1aeb0 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
1aec0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1aed0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
1aee0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
1aef0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1af00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1af10 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
1af20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1af30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1af40 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1af50 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1af60 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
1af70 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
1af80 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
1af90 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
1afa0 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
1afb0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
1afc0 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
1afd0 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
1afe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1aff0 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
1b000 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
1b010 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
1b020 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
1b030 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
1b040 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
1b050 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
1b060 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
1b070 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
1b080 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1b090 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1b0a0 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
1b0b0 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
1b0c0 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
1b0d0 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
1b0e0 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
1b0f0 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
1b100 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
1b110 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
1b120 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
1b130 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
1b140 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1b150 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1b160 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
1b170 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
1b180 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1b190 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
1b1a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
1b1b0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1b1c0 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
1b1d0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1b1e0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
1b1f0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
1b200 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1b210 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1b220 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1b230 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1b240 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b250 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1b260 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1b270 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1b280 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1b290 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
1b2a0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1b2b0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1b2c0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1b2d0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b2e0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1b2f0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
1b300 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
1b310 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45  ning Query.** ME
1b320 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1b330 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1b340 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
1b350 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
1b360 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
1b370 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
1b380 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
1b390 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
1b3a0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
1b3b0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
1b3c0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
1b3d0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
1b3e0 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
1b3f0 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
1b400 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
1b410 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
1b420 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
1b430 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
1b440 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
1b450 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
1b460 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1b470 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
1b480 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
1b490 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
1b4a0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
1b4b0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
1b4c0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
1b4d0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
1b4e0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1b4f0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
1b500 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1b510 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
1b520 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
1b530 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
1b540 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1b550 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
1b560 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
1b570 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
1b580 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
1b590 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
1b5a0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
1b5b0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
1b5c0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
1b5d0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
1b5e0 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
1b5f0 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
1b600 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
1b610 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
1b620 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
1b630 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
1b640 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
1b650 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
1b660 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
1b670 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
1b680 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1b690 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
1b6a0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
1b6b0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
1b6c0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
1b6d0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
1b6e0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
1b6f0 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
1b700 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
1b710 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
1b720 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
1b730 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
1b740 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
1b750 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
1b760 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
1b770 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
1b780 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b790 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
1b7a0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
1b7b0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1b7c0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1b7d0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1b7e0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1b7f0 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
1b800 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
1b810 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
1b820 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
1b830 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
1b840 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
1b850 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
1b860 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b870 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
1b880 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b890 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1b8a0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
1b8b0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
1b8c0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
1b8d0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
1b8e0 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
1b8f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1b900 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
1b910 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b920 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
1b930 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
1b940 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
1b950 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
1b960 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
1b970 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
1b980 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1b990 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1b9a0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1b9b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1b9c0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76  ll returns..*/.v
1b9d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1b9e0 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1b9f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ba00 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1ba10 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1ba20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1ba30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1ba40 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1ba50 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1ba60 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1ba70 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1ba80 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1ba90 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1baa0 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1bab0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1bac0 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1bad0 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1bae0 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1baf0 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1bb00 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1bb10 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1bb20 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1bb30 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1bb40 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1bb50 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1bb60 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1bb70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1bb80 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1bb90 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1bba0 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1bbb0 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1bbc0 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1bbd0 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1bbe0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1bbf0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1bc00 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1bc10 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1bc20 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1bc30 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1bc40 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1bc50 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1bc60 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1bc70 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1bc80 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1bc90 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1bca0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1bcb0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1bcc0 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1bcd0 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1bce0 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1bcf0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1bd00 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1bd10 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1bd20 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1bd30 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1bd40 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1bd50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1bd60 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1bd70 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1bd80 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1bd90 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1bda0 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1bdb0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1bdc0 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1bdd0 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1bde0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1bdf0 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1be00 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1be10 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1be20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1be30 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1be40 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1be50 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1be60 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1be70 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1be80 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1be90 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1bea0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1beb0 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1bec0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1bed0 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1bee0 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1bef0 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1bf00 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1bf10 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1bf20 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1bf30 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1bf40 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1bf50 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1bf60 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1bf70 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1bf80 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1bf90 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1bfa0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1bfb0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1bfc0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1bfd0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1bfe0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1bff0 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1c000 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1c010 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1c020 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1c030 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
1c040 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1c050 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1c060 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
1c070 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1c080 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1c090 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1c0a0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1c0b0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1c0c0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1c0d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1c0e0 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1c0f0 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1c100 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1c110 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1c120 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1c130 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1c140 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1c150 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1c160 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1c170 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1c180 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1c190 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1c1a0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1c1b0 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1c1c0 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1c1d0 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1c1e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1c1f0 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1c200 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1c210 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1c220 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1c230 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c240 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1c250 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1c260 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1c270 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1c280 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1c290 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1c2a0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1c2b0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1c2c0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1c2d0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1c2e0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1c2f0 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1c300 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1c310 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1c320 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1c330 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1c340 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1c350 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1c360 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1c370 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1c380 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1c390 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1c3a0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1c3b0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1c3c0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1c3d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1c3e0 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1c3f0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1c400 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1c410 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1c420 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1c430 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1c440 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1c450 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1c460 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1c470 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1c480 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1c490 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1c4a0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1c4b0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1c4c0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1c4d0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1c4e0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1c4f0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1c500 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1c510 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1c520 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1c530 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1c540 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1c550 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1c560 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1c570 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1c580 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1c590 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1c5a0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1c5b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1c5c0 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1c5d0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1c5e0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1c5f0 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1c600 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1c610 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1c620 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1c630 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1c640 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1c650 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1c660 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1c670 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1c680 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1c690 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1c6a0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1c6b0 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1c6c0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1c6d0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1c6e0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1c6f0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1c700 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1c710 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1c720 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1c730 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1c740 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1c750 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1c760 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1c770 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1c780 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1c790 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1c7a0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1c7b0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1c7c0 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1c7d0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1c7e0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1c7f0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1c800 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1c810 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1c820 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1c830 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1c840 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1c850 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1c860 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1c870 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1c880 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1c890 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1c8a0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1c8b0 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1c8c0 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1c8d0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1c8e0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1c8f0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1c900 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1c910 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1c920 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1c930 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1c940 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1c950 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1c960 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1c970 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1c980 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1c990 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1c9a0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1c9b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1c9c0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1c9d0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1c9e0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1c9f0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1ca00 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1ca10 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1ca20 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1ca30 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1ca40 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1ca50 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1ca60 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1ca70 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1ca80 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1ca90 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1caa0 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1cab0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1cac0 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1cad0 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1cae0 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1caf0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1cb00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1cb10 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1cb20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1cb30 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1cb40 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1cb50 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1cb60 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1cb70 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1cb80 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1cb90 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1cba0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1cbb0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1cbc0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1cbd0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1cbe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1cbf0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1cc00 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1cc10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1cc20 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1cc30 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1cc40 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1cc50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cc60 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1cc70 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1cc80 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1cc90 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1cca0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1ccb0 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1ccc0 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1ccd0 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1cce0 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1ccf0 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1cd00 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1cd10 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1cd20 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1cd30 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1cd40 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1cd50 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1cd60 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1cd70 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1cd80 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1cd90 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1cda0 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1cdb0 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1cdc0 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1cdd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1cde0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1cdf0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1ce00 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1ce10 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1ce20 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1ce30 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1ce40 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1ce50 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1ce60 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1ce70 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1ce80 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1ce90 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1cea0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1ceb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1cec0 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1ced0 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1cee0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1cef0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1cf00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1cf10 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1cf20 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1cf30 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1cf40 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1cf50 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1cf60 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1cf70 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1cf80 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1cf90 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1cfa0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1cfb0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1cfc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1cfd0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1cfe0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1cff0 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1d000 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1d010 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1d020 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1d030 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1d040 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1d050 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1d060 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1d070 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1d080 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1d090 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1d0a0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1d0b0 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1d0c0 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1d0d0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1d0e0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1d0f0 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1d100 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1d110 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1d120 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1d130 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1d140 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1d150 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1d160 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1d170 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1d180 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1d190 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1d1a0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1d1b0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1d1c0 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1d1d0 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1d1e0 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1d1f0 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1d200 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1d210 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1d220 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1d230 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1d240 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1d250 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1d260 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1d270 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1d280 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1d290 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1d2a0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1d2b0 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1d2c0 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1d2d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1d2e0 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1d2f0 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1d300 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1d310 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1d320 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1d330 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1d340 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1d350 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1d360 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1d370 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1d380 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1d390 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1d3a0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1d3b0 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1d3c0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1d3d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1d3e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1d3f0 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1d400 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1d410 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1d420 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1d430 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1d440 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1d450 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1d460 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1d470 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1d480 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1d490 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1d4a0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1d4b0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1d4c0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1d4d0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1d4e0 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1d4f0 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1d500 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1d510 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1d520 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1d530 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1d540 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1d550 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1d560 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1d570 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1d580 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1d590 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1d5a0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1d5b0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1d5c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1d5d0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1d5e0 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1d5f0 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1d600 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1d610 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1d620 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1d630 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1d640 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1d650 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1d660 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1d670 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1d680 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1d690 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1d6a0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1d6b0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1d6c0 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1d6d0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1d6e0 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1d6f0 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1d700 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1d710 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1d720 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1d730 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1d740 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1d750 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1d760 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1d770 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1d780 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d790 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1d7a0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1d7b0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1d7c0 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1d7d0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1d7e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1d7f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d800 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1d810 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1d820 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1d830 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1d840 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1d850 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1d860 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1d870 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1d880 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1d890 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1d8a0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1d8b0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1d8c0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1d8d0 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1d8e0 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1d8f0 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1d900 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1d910 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1d920 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1d930 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1d940 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1d950 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1d960 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1d970 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1d980 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1d990 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1d9a0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1d9b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d9c0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1d9d0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1d9e0 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1d9f0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1da00 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1da10 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1da20 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1da30 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1da40 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1da50 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1da60 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1da70 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1da80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1da90 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1daa0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1dab0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1dac0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1dad0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1dae0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1daf0 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1db00 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1db10 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1db20 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1db30 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1db40 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1db50 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1db60 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1db70 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1db80 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1db90 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1dba0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1dbb0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1dbc0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1dbd0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1dbe0 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1dbf0 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1dc00 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1dc10 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1dc20 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1dc30 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1dc40 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
1dc50 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1dc60 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1dc70 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1dc80 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1dc90 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1dca0 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1dcb0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1dcc0 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1dcd0 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1dce0 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1dcf0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1dd00 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1dd10 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1dd20 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1dd30 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1dd40 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1dd50 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1dd60 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1dd70 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1dd80 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1dd90 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1dda0 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
1ddb0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1ddc0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1ddd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1dde0 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1ddf0 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1de00 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1de10 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1de20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1de30 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1de40 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1de50 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1de60 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1de70 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1de80 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d  nes understand m
1de90 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f  ost of the commo
1dea0 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67  n K&R formatting
1deb0 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75   options,.** plu
1dec0 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
1ded0 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
1dee0 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64  ormats, detailed
1def0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20   below..** Note 
1df00 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65  that some of the
1df10 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f   more obscure fo
1df20 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1df30 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20   from recent.** 
1df40 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61  C-library standa
1df50 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20  rds are omitted 
1df60 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d  from this implem
1df70 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  entation..**.** 
1df80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1df90 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1dfa0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1dfb0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1dfc0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1dfd0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1dfe0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1dff0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1e000 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1e010 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1e020 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1e030 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1e040 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1e050 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1e060 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1e070 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1e080 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e090 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1e0a0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1e0b0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1e0c0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1e0d0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1e0e0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1e0f0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1e100 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1e110 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1e120 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1e130 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1e140 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1e150 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1e160 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1e170 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1e180 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1e190 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1e1a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1e1b0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1e1c0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1e1d0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1e1e0 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1e1f0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1e200 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1e210 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1e220 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1e230 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1e240 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1e250 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1e260 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1e270 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1e280 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1e290 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1e2a0 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1e2b0 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1e2c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1e2d0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1e2e0 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1e2f0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1e300 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1e310 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1e320 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1e330 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1e340 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1e350 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1e360 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1e370 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1e380 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1e390 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1e3a0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1e3b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1e3c0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1e3d0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1e3e0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1e3f0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1e400 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1e410 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1e420 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1e430 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1e440 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1e450 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1e460 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1e470 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1e480 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1e490 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1e4a0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1e4b0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1e4c0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1e4d0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1e4e0 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1e4f0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1e500 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e510 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1e520 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1e530 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1e540 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1e550 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1e560 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1e570 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1e580 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1e590 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1e5a0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1e5b0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1e5c0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1e5d0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1e5e0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1e5f0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1e600 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1e610 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1e620 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20  %q", "%Q", "%w" 
1e630 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1e640 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1e650 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1e660 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1e670 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1e680 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1e690 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1e6a0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1e6b0 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1e6c0 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1e6d0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1e6e0 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1e6f0 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1e700 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1e710 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1e720 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1e730 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1e740 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1e750 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1e760 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1e770 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1e780 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1e790 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1e7a0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1e7b0 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1e7c0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1e7d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1e7e0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1e7f0 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1e800 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1e810 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1e820 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1e830 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1e840 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1e850 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1e860 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e870 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1e880 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1e890 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1e8a0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1e8b0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1e8c0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1e8d0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1e8e0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1e8f0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1e900 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e910 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1e920 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1e930 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1e940 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1e950 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1e960 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1e970 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1e980 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1e990 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1e9a0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1e9b0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1e9c0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1e9d0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1e9e0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1e9f0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1ea00 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1ea10 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1ea20 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1ea30 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1ea40 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1ea50 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1ea60 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1ea70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1ea80 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1ea90 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1eaa0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1eab0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1eac0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1ead0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1eae0 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1eaf0 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1eb00 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1eb10 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1eb20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1eb30 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1eb40 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1eb50 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1eb60 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1eb70 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1eb80 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1eb90 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1eba0 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1ebb0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1ebc0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1ebd0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1ebe0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1ebf0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1ec00 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1ec10 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1ec20 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1ec30 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1ec40 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1ec50 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1ec60 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1ec70 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1ec80 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1ec90 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1eca0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1ecb0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1ecc0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1ecd0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1ece0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1ecf0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1ed00 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1ed10 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1ed20 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1ed30 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1ed40 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1ed50 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1ed60 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1ed70 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1ed80 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1ed90 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1eda0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1edb0 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1edc0 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b  ng option is lik
1edd0 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68  e "%q" except th
1ede0 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f  at it expects to
1edf0 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  .** be contained
1ee00 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71   within double-q
1ee10 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66  uotes instead of
1ee20 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20   single quotes, 
1ee30 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65  and it.** escape
1ee40 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f  s the double-quo
1ee50 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73  te character ins
1ee60 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67  tead of the sing
1ee70 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72  le-quote.** char
1ee80 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25  acter.)^  The "%
1ee90 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1eea0 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64  tion is intended
1eeb0 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65   for safely inse
1eec0 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61  rting.** table a
1eed0 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  nd column names 
1eee0 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74  into a construct
1eef0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1ef00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1ef10 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1ef20 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1ef30 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1ef40 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1ef50 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1ef60 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1ef70 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1ef80 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1ef90 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1efa0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1efb0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1efc0 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1efd0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1efe0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1eff0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1f000 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1f010 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1f020 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1f030 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1f040 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1f050 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1f060 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1f070 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1f080 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1f090 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1f0a0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1f0b0 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1f0c0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1f0d0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1f0e0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1f0f0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1f100 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1f110 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1f120 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1f130 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1f140 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1f150 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1f160 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1f170 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1f180 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1f190 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1f1a0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1f1b0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1f1c0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1f1d0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1f1e0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1f1f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1f200 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1f210 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1f220 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1f230 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1f240 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1f250 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1f260 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1f270 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1f280 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1f290 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1f2a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1f2b0 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1f2c0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1f2d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1f2e0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1f2f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1f300 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1f310 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1f320 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f330 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
1f340 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
1f350 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
1f360 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
1f370 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
1f380 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
1f390 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1f3a0 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
1f3b0 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
1f3c0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1f3d0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1f3e0 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1f3f0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1f400 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1f410 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1f420 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1f430 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1f440 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1f450 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1f460 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1f470 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1f480 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1f490 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1f4a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1f4b0 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1f4c0 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1f4d0 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1f4e0 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1f4f0 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1f500 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1f510 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1f520 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1f530 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1f540 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1f550 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1f560 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1f570 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1f580 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1f590 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1f5a0 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1f5b0 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1f5c0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1f5d0 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1f5e0 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1f5f0 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1f600 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1f610 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1f620 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1f630 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1f640 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1f650 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1f660 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1f670 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
1f680 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
1f690 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
1f6a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f6b0 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
1f6c0 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
1f6d0 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
1f6e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1f6f0 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
1f700 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f710 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1f720 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1f730 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1f740 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
1f750 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
1f760 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1f770 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1f780 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1f790 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1f7a0 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1f7b0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1f7c0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1f7d0 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
1f7e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f7f0 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
1f800 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1f810 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1f820 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1f830 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1f840 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
1f850 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
1f860 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1f870 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1f880 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1f890 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1f8a0 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
1f8b0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1f8c0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
1f8d0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1f8e0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1f8f0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1f900 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1f910 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
1f920 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1f930 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1f940 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f950 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
1f960 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
1f970 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
1f980 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1f990 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1f9a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f9b0 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
1f9c0 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
1f9d0 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
1f9e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1f9f0 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
1fa00 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
1fa10 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
1fa20 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
1fa30 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
1fa40 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
1fa50 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
1fa60 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
1fa70 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
1fa80 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1fa90 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
1faa0 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
1fab0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
1fac0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fad0 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
1fae0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1faf0 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
1fb00 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
1fb10 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
1fb20 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
1fb30 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1fb40 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
1fb50 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
1fb60 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
1fb70 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
1fb80 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
1fb90 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
1fba0 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
1fbb0 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
1fbc0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1fbd0 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
1fbe0 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
1fbf0 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
1fc00 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
1fc10 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
1fc20 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
1fc30 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
1fc40 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
1fc50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1fc60 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
1fc70 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
1fc80 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
1fc90 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
1fca0 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
1fcb0 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
1fcc0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
1fcd0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
1fce0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1fcf0 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
1fd00 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1fd10 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1fd20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1fd30 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
1fd40 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1fd50 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1fd60 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1fd70 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1fd80 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1fd90 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1fda0 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1fdb0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1fdc0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1fdd0 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1fde0 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1fdf0 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1fe00 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1fe10 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1fe20 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1fe30 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1fe40 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1fe50 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1fe60 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1fe70 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1fe80 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1fe90 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1fea0 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1feb0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1fec0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1fed0 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1fee0 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1fef0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1ff00 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
1ff10 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1ff20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
1ff30 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1ff40 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1ff50 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1ff60 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1ff70 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1ff80 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1ff90 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1ffa0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1ffb0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1ffc0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1ffd0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1ffe0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1fff0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
20000 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
20010 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
20020 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
20030 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
20040 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
20050 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
20060 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
20070 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
20080 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
20090 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
200a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
200b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
200c0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
200d0 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
200e0 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
200f0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
20100 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
20110 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
20120 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
20130 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20140 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
20150 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
20160 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
20170 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
20180 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
20190 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
201a0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
201b0 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
201c0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
201d0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
201e0 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
201f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
20200 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
20210 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
20220 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
20230 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
20240 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71  int64);.void *sq
20250 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
20260 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
20270 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
20280 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
20290 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
202a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
202b0 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e  d*);.sqlite3_uin
202c0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
202d0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
202e0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
202f0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
20300 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
20310 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
20320 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
20330 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
20340 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
20350 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
20360 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
20370 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
20380 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
20390 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
203a0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
203b0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
203c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
203d0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
203e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
203f0 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
20400 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
20410 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
20420 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
20430 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
20440 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
20450 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
20460 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
20470 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
20480 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
20490 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
204a0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
204b0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
204c0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
204d0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
204e0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
204f0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
20500 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
20510 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
20520 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
20530 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20540 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
20550 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
20560 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
20570 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
20580 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
20590 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
205a0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
205b0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
205c0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
205d0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
205e0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
205f0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
20600 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
20610 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
20620 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
20630 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
20640 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
20650 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20660 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
20670 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
20680 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
20690 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
206a0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
206b0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
206c0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
206d0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
206e0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
206f0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
20700 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
20710 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
20720 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
20730 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
20740 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
20750 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20760 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
20770 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
20780 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
20790 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
207a0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
207b0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
207c0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
207d0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
207e0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
207f0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
20800 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
20810 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
20820 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
20830 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
20840 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
20850 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
20860 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
20870 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
20880 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
20890 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
208a0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
208b0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
208c0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
208d0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
208e0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
208f0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
20900 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
20910 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
20920 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
20930 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
20940 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
20950 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
20960 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
20970 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
20980 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
20990 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
209a0 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
209b0 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
209c0 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
209d0 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
209e0 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
209f0 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
20a00 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
20a10 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
20a20 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
20a30 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
20a40 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
20a50 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
20a60 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
20a70 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
20a80 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
20a90 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
20aa0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
20ab0 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
20ac0 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
20ad0 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
20ae0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
20af0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
20b00 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
20b10 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
20b20 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
20b30 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
20b40 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
20b50 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
20b60 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
20b70 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
20b80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20b90 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
20ba0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
20bb0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
20bc0 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f  sqlite3.** KEYWO
20bd0 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72  RDS: {authorizer
20be0 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a   callback}.**.**
20bf0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
20c00 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
20c10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20c20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
20c30 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
20c40 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
20c50 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
20c60 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
20c70 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
20c80 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
20c90 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
20ca0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
20cb0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
20cc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
20cd0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
20ce0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
20cf0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
20d00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
20d10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
20d20 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
20d30 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
20d40 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
20d50 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
20d60 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
20d70 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
20d80 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
20d90 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
20da0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20db0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
20dc0 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
20dd0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
20de0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
20df0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20e00 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
20e10 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
20e20 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
20e30 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
20e40 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
20e50 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
20e60 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
20e70 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
20e80 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
20e90 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
20ea0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
20eb0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
20ec0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
20ed0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
20ee0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
20ef0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
20f00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20f10 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
20f20 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
20f30 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
20f40 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
20f50 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
20f60 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
20f70 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
20f80 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
20f90 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
20fa0 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
20fb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
20fc0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
20fd0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
20fe0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
20ff0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
21000 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
21010 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
21020 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
21030 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
21040 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
21050 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
21060 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
21070 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21080 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
21090 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
210a0 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
210b0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
210c0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
210d0 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
210e0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
210f0 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
21100 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
21110 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
21120 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21130 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
21140 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
21150 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
21160 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21170 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
21180 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
21190 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
211a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
211b0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
211c0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
211d0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
211e0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
211f0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
21200 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
21210 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
21220 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
21230 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
21240 61 63 6b 20 61 72 65 20 65 69 74 68 65 72 20 4e  ack are either N
21250 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6f 72 20  ULL pointers or 
21260 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
21270 73 74 72 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20  strings.** that 
21280 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
21290 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  al details about
212a0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
212b0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
212c0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
212d0 73 74 20 61 6c 77 61 79 73 20 62 65 20 70 72 65  st always be pre
212e0 70 61 72 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74  pared to encount
212f0 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
21300 72 20 69 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  r in any.** of t
21310 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
21320 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d   the sixth param
21330 65 74 65 72 73 20 6f 66 20 74 68 65 20 61 75 74  eters of the aut
21340 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62  horization callb
21350 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ack..**.** ^If t
21360 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
21370 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
21380 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
21390 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
213a0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
213b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
213c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
213d0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
213e0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
213f0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
21400 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
21410 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
21420 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
21430 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
21440 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
21450 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
21460 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
21470 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
21480 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
21490 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
214a0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
214b0 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
214c0 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
214d0 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 74 61 62 6c  .** ^When a tabl
214e0 65 20 69 73 20 72 65 66 65 72 65 6e 63 65 64 20  e is referenced 
214f0 62 79 20 61 20 5b 53 45 4c 45 43 54 5d 20 62 75  by a [SELECT] bu
21500 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  t no column valu
21510 65 73 20 61 72 65 0a 2a 2a 20 65 78 74 72 61 63  es are.** extrac
21520 74 65 64 20 66 72 6f 6d 20 74 68 61 74 20 74 61  ted from that ta
21530 62 6c 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ble (for example
21540 20 69 6e 20 61 20 71 75 65 72 79 20 6c 69 6b 65   in a query like
21550 0a 2a 2a 20 22 53 45 4c 45 43 54 20 63 6f 75 6e  .** "SELECT coun
21560 74 28 2a 29 20 46 52 4f 4d 20 74 61 62 22 29 20  t(*) FROM tab") 
21570 74 68 65 6e 20 74 68 65 20 5b 53 51 4c 49 54 45  then the [SQLITE
21580 5f 52 45 41 44 5d 20 61 75 74 68 6f 72 69 7a 65  _READ] authorize
21590 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
215a0 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
215b0 72 20 74 68 61 74 20 74 61 62 6c 65 20 77 69 74  r that table wit
215c0 68 20 61 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20  h a column name 
215d0 74 68 61 74 20 69 73 20 61 6e 20 65 6d 70 74 79  that is an empty
215e0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
215f0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
21600 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
21610 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
21620 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
21630 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
21640 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
21650 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
21660 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
21670 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
21680 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
21690 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
216a0 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
216b0 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
216c0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
216d0 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
216e0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
216f0 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
21700 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
21710 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
21720 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
21730 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
21740 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
21750 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
21760 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
21770 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
21780 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
21790 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
217a0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
217b0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
217c0 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
217d0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
217e0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
217f0 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
21800 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
21810 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
21820 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
21830 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
21840 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
21850 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
21860 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
21870 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
21880 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
21890 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
218a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
218b0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
218c0 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
218d0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
218e0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
218f0 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
21900 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21910 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
21920 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
21930 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
21940 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
21950 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
21960 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
21970 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
21980 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
21990 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
219a0 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
219b0 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
219c0 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
219d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
219e0 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
219f0 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
21a00 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
21a10 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
21a20 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
21a30 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
21a40 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
21a50 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
21a60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
21a70 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
21a80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21a90 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
21aa0 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
21ab0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21ac0 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
21ad0 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
21ae0 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
21af0 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
21b00 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
21b10 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
21b20 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
21b30 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
21b40 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
21b50 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
21b60 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
21b70 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
21b80 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
21b90 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
21ba0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
21bb0 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
21bc0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
21bd0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
21be0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21bf0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
21c00 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
21c10 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
21c20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21c30 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
21c40 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
21c50 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
21c60 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
21c70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21c80 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
21c90 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
21ca0 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
21cb0 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
21cc0 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
21cd0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
21ce0 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
21cf0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
21d00 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
21d10 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
21d20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
21d30 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
21d40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
21d50 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
21d60 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
21d70 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
21d80 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
21d90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21da0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
21db0 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
21dc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
21dd0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
21de0 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
21df0 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
21e00 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
21e10 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
21e20 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
21e30 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
21e40 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
21e50 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
21e60 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
21e70 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
21e80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21e90 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
21ea0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
21eb0 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
21ec0 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
21ed0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21ee0 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
21ef0 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
21f00 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
21f10 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
21f20 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
21f30 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
21f40 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
21f50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21f60 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
21f70 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
21f80 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
21f90 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
21fa0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21fb0 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
21fc0 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
21fd0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
21fe0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
21ff0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
22000 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
22010 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
22020 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
22030 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
22040 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
22050 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
22060 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
22070 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
22080 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
22090 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
220a0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
220b0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
220c0 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
220d0 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74  conflict resolut
220e0 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74  ion mode].** ret
220f0 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b  urned from the [
22100 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
22110 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
22120 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
22130 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
22140 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
22150 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
22160 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
22170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
22180 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
22190 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
221a0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
221b0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
221c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
221d0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
221e0 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
221f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
22200 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
22210 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
22220 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
22230 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
22240 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
22250 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
22260 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
22270 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
22280 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
22290 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
222a0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
222b0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
222c0 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
222d0 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
222e0 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
222f0 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
22300 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
22310 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22320 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
22330 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
22340 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
22350 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
22360 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
22370 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
22380 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
22390 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
223a0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
223b0 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
223c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
223d0 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
223e0 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
223f0 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
22400 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
22410 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
22420 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
22430 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
22440 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
22450 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
22460 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
22470 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
22480 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
22490 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
224a0 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
224b0 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
224c0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
224d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
224e0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
224f0 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
22500 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
22510 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
22520 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
22530 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
22540 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
22550 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
22560 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
22570 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
22580 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
22590 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
225a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
225b0 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
225c0 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
225d0 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
225e0 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
225f0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
22600 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
22610 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22620 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22630 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
22640 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
22650 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22660 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22670 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22680 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
22690 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
226a0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
226b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
226c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
226d0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
226e0 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
226f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22700 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22710 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22720 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
22730 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
22740 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
22750 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22760 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22770 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
22780 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
22790 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
227a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
227b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
227c0 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
227d0 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
227e0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
227f0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22800 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22810 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
22820 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
22830 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
22840 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22850 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
22860 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
22870 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
22880 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22890 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
228a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
228b0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
228c0 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
228d0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
228e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
228f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22900 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
22910 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
22920 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22930 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22940 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
22950 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
22960 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
22970 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
22980 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22990 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
229a0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
229b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
229c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
229d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
229e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
229f0 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
22a00 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
22a10 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22a20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22a30 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
22a40 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
22a50 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
22a60 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22a70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22a80 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
22a90 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
22aa0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
22ab0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22ac0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22ad0 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
22ae0 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
22af0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
22b00 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22b10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22b20 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
22b30 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
22b40 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22b50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22b60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22b70 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
22b80 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
22b90 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
22ba0 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
22bb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22bc0 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
22bd0 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
22be0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
22bf0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
22c00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22c10 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
22c20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
22c30 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
22c40 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22c50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
22c60 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
22c70 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
22c80 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
22c90 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22ca0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
22cb0 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
22cc0 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
22cd0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
22ce0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
22cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
22d00 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
22d10 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
22d20 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
22d30 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
22d50 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
22d60 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
22d70 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
22d80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22d90 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
22da0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
22db0 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
22dc0 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
22dd0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22de0 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
22df0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
22e00 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
22e10 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22e20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22e30 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
22e40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
22e50 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22e60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22e70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22e80 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
22e90 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
22ea0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22eb0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
22ec0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22ed0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
22ee0 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
22ef0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22f00 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
22f10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22f20 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
22f30 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
22f40 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
22f50 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
22f60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22f70 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
22f80 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
22f90 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
22fa0 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
22fb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22fc0 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
22fd0 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
22fe0 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
22ff0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23000 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20  E_RECURSIVE     
23010 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e         33   /* N
23020 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
23030 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23040 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
23050 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
23060 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
23070 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
23080 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73  lite3.**.** Thes
23090 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
230a0 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20 74  eprecated. Use t
230b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
230c0 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  e_v2()] interfac
230d0 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20  e.** instead of 
230e0 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73  the routines des
230f0 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  cribed here..**.
23100 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
23110 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
23120 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
23130 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
23140 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
23150 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
23160 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
23170 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
23180 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
23190 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
231a0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
231b0 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
231c0 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
231d0 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
231e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
231f0 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
23200 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
23210 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
23220 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
23230 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
23240 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
23250 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
23260 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
23270 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
23280 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
23290 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
232a0 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
232b0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
232c0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
232d0 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
232e0 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
232f0 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
23300 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
23310 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
23320 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
23330 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
23340 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
23350 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
23360 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
23370 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
23380 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
23390 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
233a0 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
233b0 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
233c0 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
233d0 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
233e0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
233f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
23400 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
23410 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
23420 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
23430 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
23440 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
23450 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
23460 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
23470 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
23480 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
23490 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
234a0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
234b0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
234c0 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
234d0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
234e0 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
234f0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
23500 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
23510 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
23520 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
23530 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
23540 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
23550 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
23560 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
23570 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
23580 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
23590 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
235a0 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
235b0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
235c0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
235d0 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
235e0 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
235f0 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
23600 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
23610 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
23620 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
23630 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
23640 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
23650 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
23660 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
23670 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
23680 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
23690 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
236a0 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
236b0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
236c0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
236d0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
236e0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  void*);.SQLITE_D
236f0 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a  EPRECATED void *
23700 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
23710 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
23720 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
23730 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
23740 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
23750 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
23760 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61  API3REF: SQL Tra
23770 63 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a  ce Event Codes.*
23780 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
23790 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54  TE_TRACE.**.** T
237a0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69  hese constants i
237b0 64 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20  dentify classes 
237c0 6f 66 20 65 76 65 6e 74 73 20 74 68 61 74 20 63  of events that c
237d0 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a  an be monitored.
237e0 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ** using the [sq
237f0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
23800 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e  ] tracing logic.
23810 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
23820 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
23830 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
23840 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62  is an OR-ed comb
23850 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f  ination of one o
23860 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65  r more of.** the
23870 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74   following const
23880 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73  ants.  ^The firs
23890 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
238a0 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
238b0 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  .** is one of th
238c0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73  e following cons
238d0 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  tants..**.** New
238e0 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e   tracing constan
238f0 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ts may be added 
23900 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
23910 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61  es..**.** ^A tra
23920 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20  ce callback has 
23930 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20  four arguments: 
23940 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c  xCallback(T,C,P,
23950 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72  X)..** ^The T ar
23960 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
23970 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79 70   the integer typ
23980 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a  e codes above..*
23990 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e  * ^The C argumen
239a0 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  t is a copy of t
239b0 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  he context point
239c0 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  er passed in as 
239d0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72  the.** fourth ar
239e0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
239f0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a  e3_trace_v2()]..
23a00 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61  ** The P and X a
23a10 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69  rguments are poi
23a20 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e  nters whose mean
23a30 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54  ings depend on T
23a40 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
23a50 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  [[SQLITE_TRACE_S
23a60 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TMT]] <dt>SQLITE
23a70 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e  _TRACE_STMT</dt>
23a80 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
23a90 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61  TE_TRACE_STMT ca
23aa0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
23ab0 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72 65  d when a prepare
23ac0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66  d statement.** f
23ad0 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e  irst begins runn
23ae0 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79  ing and possibly
23af0 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20   at other times 
23b00 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78  during the.** ex
23b10 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70  ecution of the p
23b20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23b30 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74 68  t, such as at th
23b40 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a  e start of each.
23b50 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70 72  ** trigger subpr
23b60 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72  ogram. ^The P ar
23b70 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
23b80 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70  ter to the.** [p
23b90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23ba0 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d  t]. ^The X argum
23bb0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
23bc0 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
23bd0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65  ch.** is the une
23be0 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74  xpanded SQL text
23bf0 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
23c00 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e   statement or an
23c10 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a   SQL comment .**
23c20 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
23c30 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  the invocation o
23c40 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54  f a trigger.  ^T
23c50 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20  he callback can 
23c60 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73  compute.** the s
23c70 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77 6f  ame text that wo
23c80 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72 65  uld have been re
23c90 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65  turned by the le
23ca0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72  gacy [sqlite3_tr
23cb0 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ace()].** interf
23cc0 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68 65  ace by using the
23cd0 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e   X argument when
23ce0 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20 22   X begins with "
23cf0 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  --" and invoking
23d00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70  .** [sqlite3_exp
23d10 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74  anded_sql(P)] ot
23d20 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b  herwise..**.** [
23d30 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52  [SQLITE_TRACE_PR
23d40 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  OFILE]] <dt>SQLI
23d50 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
23d60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
23d70 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
23d80 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70  OFILE callback p
23d90 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d  rovides approxim
23da0 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a  ately the same.*
23db0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  * information as
23dc0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
23dd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  the [sqlite3_pro
23de0 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b  file()] callback
23df0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75  ..** ^The P argu
23e00 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
23e10 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
23e20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
23e30 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d  d the.** X argum
23e40 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
23e50 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77  64-bit integer w
23e60 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74 69  hich is the esti
23e70 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20  mated of.** the 
23e80 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65  number of nanose
23e90 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70 72  cond that the pr
23ea0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23eb0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
23ec0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41   ^The SQLITE_TRA
23ed0 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62  CE_PROFILE callb
23ee0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23ef0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
23f00 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a  t finishes..**.*
23f10 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
23f20 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _ROW]] <dt>SQLIT
23f30 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e  E_TRACE_ROW</dt>
23f40 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
23f50 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c  TE_TRACE_ROW cal
23f60 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
23f70 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65 70   whenever a prep
23f80 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
23f90 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73 69  t generates a si
23fa0 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75  ngle row of resu
23fb0 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20  lt.  .** ^The P 
23fc0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
23fd0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72  inter to the [pr
23fe0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23ff0 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61  ] and the.** X a
24000 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65  rgument is unuse
24010 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d..**.** [[SQLIT
24020 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20  E_TRACE_CLOSE]] 
24030 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
24040 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
24050 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
24060 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61  ACE_CLOSE callba
24070 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
24080 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  en a database.**
24090 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
240a0 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  es..** ^The P ar
240b0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
240c0 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
240d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
240e0 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74   object.** and t
240f0 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  he X argument is
24100 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c   unused..** </dl
24110 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
24120 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20  ITE_TRACE_STMT  
24130 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e       0x01.#defin
24140 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  e SQLITE_TRACE_P
24150 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23  ROFILE    0x02.#
24160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
24170 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30  ACE_ROW        0
24180 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x04.#define SQLI
24190 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20  TE_TRACE_CLOSE  
241a0 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20      0x08../*.** 
241b0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72  CAPI3REF: SQL Tr
241c0 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48  ace Hook.** METH
241d0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
241e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
241f0 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29  race_v2(D,M,X,P)
24200 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
24210 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61 6c  ters a trace cal
24220 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
24230 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74  n X against [dat
24240 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24250 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65  ] D, using prope
24260 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e  rty mask M.** an
24270 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  d context pointe
24280 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20  r P.  ^If the X 
24290 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e  callback is.** N
242a0 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20  ULL or if the M 
242b0 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68  mask is zero, th
242c0 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64 69  en tracing is di
242d0 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  sabled.  The.** 
242e0 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  M argument shoul
242f0 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73 65  d be the bitwise
24300 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
24310 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72  on of.** zero or
24320 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52   more [SQLITE_TR
24330 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  ACE] constants..
24340 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c  **.** ^Each call
24350 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74   to either sqlit
24360 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71  e3_trace() or sq
24370 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
24380 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28   overrides .** (
24390 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69  cancels) any pri
243a0 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  or calls to sqli
243b0 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73  te3_trace() or s
243c0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
243d0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20  )..**.** ^The X 
243e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
243f0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79  ked whenever any
24400 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20 69   of the events i
24410 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a  dentified by .**
24420 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20   mask M occur.  
24430 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65 74  ^The integer ret
24440 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74  urn value from t
24450 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63  he callback is c
24460 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f  urrently.** igno
24470 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73  red, though this
24480 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66   may change in f
24490 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20  uture releases. 
244a0 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70   Callback.** imp
244b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
244c0 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20  uld return zero 
244d0 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72 65  to ensure future
244e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
244f0 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63  **.** ^A trace c
24500 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
24510 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72 67  ed with four arg
24520 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b  uments: callback
24530 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54  (T,C,P,X)..** ^T
24540 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73  he T argument is
24550 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c   one of the [SQL
24560 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f  ITE_TRACE].** co
24570 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63  nstants to indic
24580 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c  ate why the call
24590 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64  back was invoked
245a0 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75  ..** ^The C argu
245b0 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f  ment is a copy o
245c0 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f  f the context po
245d0 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20  inter..** The P 
245e0 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20  and X arguments 
245f0 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f  are pointers who
24600 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65  se meanings depe
24610 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54  nd on T..**.** T
24620 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
24630 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
24640 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72  is intended to r
24650 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63  eplace the legac
24660 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
24670 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
24680 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
24690 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20  rofile()], both 
246a0 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20  of which.** are 
246b0 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69  deprecated..*/.i
246c0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  nt sqlite3_trace
246d0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
246e0 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73  .  unsigned uMas
246f0 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62  k,.  int(*xCallb
24700 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f  ack)(unsigned,vo
24710 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29  id*,void*,void*)
24720 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29  ,.  void *pCtx.)
24730 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24740 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
24750 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  s Callbacks.** M
24760 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
24770 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
24780 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
24790 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
247a0 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
247b0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
247c0 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
247d0 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
247e0 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
247f0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
24800 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
24810 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
24820 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
24830 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
24840 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
24850 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
24860 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
24870 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
24880 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
24890 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
248a0 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
248b0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
248c0 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
248d0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
248e0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
248f0 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
24900 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
24910 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
24920 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f  r N is the appro
24930 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66  ximate number of
24940 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
24950 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
24960 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
24970 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
24980 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
24990 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
249a0 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66  callback X.  ^If
249b0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
249c0 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f  one then the pro
249d0 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72  gress.** handler
249e0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a   is disabled..**
249f0 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
24a00 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
24a10 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
24a20 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
24a30 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
24a40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
24a50 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
24a60 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
24a70 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
24a80 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
24a90 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
24aa0 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
24ab0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
24ac0 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
24ad0 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
24ae0 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
24af0 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
24b00 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
24b10 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
24b20 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
24b30 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
24b40 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
24b50 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
24b60 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
24b70 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
24b80 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
24b90 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
24ba0 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
24bb0 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
24bc0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
24bd0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
24be0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
24bf0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
24c00 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
24c10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24c20 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
24c30 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
24c40 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
24c50 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
24c60 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
24c70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24c80 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
24c90 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
24ca0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
24cb0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
24cc0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
24cd0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
24ce0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
24cf0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
24d00 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
24d10 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
24d20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
24d30 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
24d40 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
24d50 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52  ection.** CONSTR
24d60 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a  UCTOR: sqlite3.*
24d70 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
24d80 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
24d90 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
24da0 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62  e as specified b
24db0 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61  y the .** filena
24dc0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68  me argument. ^Th
24dd0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
24de0 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
24df0 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
24e00 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
24e10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
24e20 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
24e30 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
24e40 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
24e50 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
24e60 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74  en16(). ^(A [dat
24e70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24e80 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
24e90 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
24ea0 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
24eb0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
24ec0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
24ed0 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
24ee0 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
24ef0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
24f00 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
24f10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
24f20 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
24f30 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
24f40 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
24f50 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
24f60 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
24f70 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e  ].** object.)^ ^
24f80 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  (If the database
24f90 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
24fa0 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
24fb0 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
24fc0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
24fd0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
24fe0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
24ff0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
25000 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71  d.)^ ^The.** [sq
25010 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
25020 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
25030 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
25040 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
25050 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
25060 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
25070 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
25080 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67   error following
25090 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e   a failure of an
250a0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  y.** of the sqli
250b0 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69  te3_open() routi
250c0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nes..**.** ^The 
250d0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
250e0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66   will be UTF-8 f
250f0 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65  or databases cre
25100 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71  ated using.** sq
25110 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
25120 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25130 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  ).  ^The default
25140 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61   encoding for da
25150 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74  tabases.** creat
25160 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
25170 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62  _open16() will b
25180 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  e UTF-16 in the 
25190 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
251a0 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  r..**.** Whether
251b0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
251c0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
251d0 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
251e0 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
251f0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
25200 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25210 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
25220 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
25230 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
25240 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
25250 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
25260 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
25270 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25280 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
25290 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
252a0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
252b0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
252c0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
252d0 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
252e0 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
252f0 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
25300 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
25310 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
25320 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
25330 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
25340 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25350 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
25360 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
25370 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
25380 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
25390 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
253a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
253b0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
253c0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
253d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
253e0 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
253f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
25400 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
25410 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
25420 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
25430 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
25440 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
25450 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
25460 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
25470 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
25480 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
25490 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
254a0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
254b0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
254c0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
254d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
254e0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
254f0 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
25500 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
25510 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
25520 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
25530 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
25540 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
25550 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
25560 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
25570 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
25580 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
25590 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
255a0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
255b0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
255c0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
255d0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
255e0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
255f0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
25600 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
25610 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
25620 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
25630 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
25640 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
25650 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
25660 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
25670 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
25680 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
25690 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
256a0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
256b0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
256c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
256d0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
256e0 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
256f0 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
25700 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
25710 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25720 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
25730 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
25740 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
25750 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
25760 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
25770 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
25780 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
25790 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
257a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
257b0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
257c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
257d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
257e0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
257f0 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
25800 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25810 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
25820 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
25830 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
25840 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
25850 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
25860 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
25870 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
25880 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
25890 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
258a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
258b0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
258c0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
258d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
258e0 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
258f0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
25900 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
25910 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
25920 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
25930 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
25940 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
25950 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
25960 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
25970 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
25980 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
25990 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
259a0 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
259b0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
259c0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
259d0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
259e0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
259f0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
25a00 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
25a10 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
25a20 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
25a30 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
25a40 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
25a50 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
25a60 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25a70 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
25a80 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
25a90 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
25aa0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
25ab0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
25ac0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
25ad0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25ae0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
25af0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
25b00 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
25b10 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
25b20 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
25b30 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
25b40 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
25b50 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
25b60 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
25b70 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
25b80 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
25b90 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
25ba0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
25bb0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
25bc0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
25bd0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
25be0 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
25bf0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
25c00 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
25c10 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
25c20 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
25c30 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
25c40 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
25c50 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
25c60 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
25c70 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
25c80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
25c90 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
25ca0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
25cb0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
25cc0 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
25cd0 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
25ce0 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
25cf0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
25d00 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
25d10 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
25d20 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
25d30 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
25d40 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
25d50 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
25d60 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
25d70 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
25d80 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
25d90 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
25da0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
25db0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
25dc0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
25dd0 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
25de0 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
25df0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
25e00 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
25e10 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
25e20 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
25e30 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
25e40 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
25e50 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
25e60 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
25e70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
25e80 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
25e90 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
25ea0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
25eb0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
25ec0 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
25ed0 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
25ee0 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
25ef0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
25f00 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
25f10 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
25f20 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
25f30 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
25f40 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
25f50 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
25f60 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
25f70 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
25f80 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
25f90 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
25fa0 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
25fb0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
25fc0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
25fd0 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
25fe0 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
25ff0 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
26000 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
26010 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
26020 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
26030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
26040 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
26050 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
26060 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
26070 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
26080 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
26090 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
260a0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
260b0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
260c0 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
260d0 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
260e0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
260f0 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
26100 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
26110 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
26120 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
26130 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
26140 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
26150 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
26160 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
26170 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
26180 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
26190 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
261a0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
261b0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
261c0 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
261d0 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
261e0 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
261f0 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
26200 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
26210 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
26220 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
26230 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
26240 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
26250 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
26260 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
26270 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
26280 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
26290 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
262a0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
262b0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
262c0 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
262d0 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
262e0 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
262f0 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
26300 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
26310 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
26320 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
26330 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
26340 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
26350 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
26360 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
26370 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
26380 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
26390 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
263a0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
263b0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
263c0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
263d0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
263e0 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
263f0 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
26400 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77  path. .** ^(On w
26410 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
26420 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
26430 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
26440 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
26450 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
26460 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a  g. "C:").)^.**.*
26470 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
26480 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
26490 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
264a0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
264b0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
264c0 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
264d0 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
264e0 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
264f0 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
26500 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
26510 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
26520 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  ]..** SQLite and
26530 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56   its built-in [V
26540 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20  FSes] interpret 
26550 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
26560 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26570 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
26580 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
26590 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
265a0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
265b0 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
265c0 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
265d0 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
265e0 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
265f0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
26600 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
26610 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
26620 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
26630 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
26640 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
26650 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
26660 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
26670 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
26680 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
26690 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
266a0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
266b0 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
266c0 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
266d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
266e0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
266f0 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
26700 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
26710 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
26720 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
26730 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
26740 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
26750 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
26760 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
26770 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
26780 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26790 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
267a0 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
267b0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
267c0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
267d0 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
267e0 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20  ,.**     "rwc", 
267f0 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74  or "memory". Att
26800 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
26810 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
26820 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61  alue is.**     a
26830 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
26840 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
26850 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
26860 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
26870 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
26880 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
26890 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
268a0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
268b0 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
268c0 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
268d0 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
268e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
268f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
26900 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
26910 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a  ion is set to .*
26920 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e  *     "rw", then
26930 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
26940 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
26950 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20  -write (but not 
26960 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20  create) .**     
26970 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51  access, as if SQ
26980 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
26990 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c  ITE (but not SQL
269a0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29  ITE_OPEN_CREATE)
269b0 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65   had .**     bee
269c0 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72  n set. ^Value "r
269d0 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  wc" is equivalen
269e0 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74  t to setting bot
269f0 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  h .**     SQLITE
26a00 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
26a10 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  and SQLITE_OPEN_
26a20 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65  CREATE.  ^If the
26a30 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a   mode option is.
26a40 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d  **     set to "m
26a50 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75  emory" then a pu
26a60 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  re [in-memory da
26a70 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76  tabase] that nev
26a80 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20  er reads.**     
26a90 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64  or writes from d
26aa0 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74  isk is used. ^It
26ab0 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
26ac0 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20  specify a value 
26ad0 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d  for.**     the m
26ae0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  ode parameter th
26af0 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72  at is less restr
26b00 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74  ictive than that
26b10 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
26b20 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70       the flags p
26b30 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69  assed in the thi
26b40 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
26b50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26b60 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
26b70 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54  <b>cache</b>: ^T
26b80 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
26b90 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
26ba0 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22   either "shared"
26bb0 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76   or.**     "priv
26bc0 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69  ate". ^Setting i
26bd0 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73  t to "shared" is
26be0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
26bf0 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  etting the.**   
26c00 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48    SQLITE_OPEN_SH
26c10 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e  AREDCACHE bit in
26c20 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
26c30 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ent passed to.**
26c40 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65       sqlite3_ope
26c50 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67  n_v2(). ^Setting
26c60 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d   the cache param
26c70 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65  eter to "private
26c80 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75  " is .**     equ
26c90 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
26ca0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  ng the SQLITE_OP
26cb0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
26cc0 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20  bit..**     ^If 
26cd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26ce0 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
26cf0 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65  e "cache" parame
26d00 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69  ter is present i
26d10 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66  n.**     a URI f
26d20 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c  ilename, its val
26d30 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  ue overrides any
26d40 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73   behavior reques
26d50 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
26d60 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
26d70 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
26d80 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
26d90 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
26da0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70  **.**  <li> <b>p
26db0 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73  sow</b>: ^The ps
26dc0 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64  ow parameter ind
26dd0 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f  icates whether o
26de0 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20  r not the.**    
26df0 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72   [powersafe over
26e00 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20  write] property 
26e10 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74  does or does not
26e20 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a   apply to the.**
26e30 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64       storage med
26e40 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20  ia on which the 
26e50 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65  database file re
26e60 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  sides..**.**  <l
26e70 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e  i> <b>nolock</b>
26e80 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61  : ^The nolock pa
26e90 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
26ea0 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d  lean query param
26eb0 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63  eter.**     whic
26ec0 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65  h if set disable
26ed0 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69  s file locking i
26ee0 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e  n rollback journ
26ef0 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a  al modes.  This.
26f00 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c  **     is useful
26f10 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61   for accessing a
26f20 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66   database on a f
26f30 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64  ilesystem that d
26f40 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73  oes not.**     s
26f50 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20  upport locking. 
26f60 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62   Caution:  Datab
26f70 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d  ase corruption m
26f80 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74  ight result if t
26f90 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72  wo.**     or mor
26fa0 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74  e processes writ
26fb0 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  e to the same da
26fc0 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f  tabase and any o
26fd0 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20  ne of those.**  
26fe0 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65     processes use
26ff0 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a  s nolock=1..**.*
27000 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74  *  <li> <b>immut
27010 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69  able</b>: ^The i
27020 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74  mmutable paramet
27030 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
27040 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72  query.**     par
27050 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69  ameter that indi
27060 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64  cates that the d
27070 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
27080 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20  stored on.**    
27090 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
270a0 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62  .  ^When immutab
270b0 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74  le is set, SQLit
270c0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
270d0 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61  he.**     databa
270e0 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62  se file cannot b
270f0 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20  e changed, even 
27100 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74  by a process wit
27110 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20  h higher.**     
27120 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73  privilege, and s
27130 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  o the database i
27140 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e  s opened read-on
27150 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69  ly and all locki
27160 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68  ng.**     and ch
27170 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69  ange detection i
27180 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75  s disabled.  Cau
27190 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68  tion: Setting th
271a0 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20  e immutable.**  
271b0 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61     property on a
271c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
271d0 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74  hat does in fact
271e0 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75   change can resu
271f0 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63  lt.**     in inc
27200 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73  orrect query res
27210 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  ults and/or [SQL
27220 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72  ITE_CORRUPT] err
27230 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20  ors..**     See 
27240 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
27250 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a  CAP_IMMUTABLE]..
27260 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75  **       .** </u
27270 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
27280 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
27290 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
272a0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
272b0 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
272c0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
272d0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
272e0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
272f0 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
27300 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
27310 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
27320 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
27330 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
27340 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
27350 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
27360 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
27370 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
27380 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
27390 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
273a0 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
273b0 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
273c0 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
273d0 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
273e0 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
273f0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
27400 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
27410 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
27420 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
27430 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
27440 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
27450 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
27460 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
27470 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
27480 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
27490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
274a0 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
274b0 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
274c0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
274d0 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
274e0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
274f0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
27500 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
27510 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
27520 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
27530 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
27540 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
27550 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
27560 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
27570 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
27580 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
27590 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
275a0 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
275b0 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
275c0 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
275d0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
275e0 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
275f0 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
27600 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
27610 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
27620 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
27630 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
27640 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
27650 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
27660 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
27670 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
27680 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
27690 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
276a0 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
276b0 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
276c0 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
276d0 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
276e0 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
276f0 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
27700 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
27710 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
27720 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
27730 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
27740 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
27750 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
27760 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
27770 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
27780 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
27790 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
277a0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
277b0 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
277c0 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
277d0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
277e0 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
277f0 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
27800 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
27810 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
27820 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74  .db?vfs=unix-dot
27830 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  file <td>.**    
27840 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
27850 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
27860 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
27870 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
27880 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20  dotfile".**     
27890 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64       that uses d
278a0 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63  ot-files in plac
278b0 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73  e of posix advis
278c0 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20  ory locking..** 
278d0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
278e0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
278f0 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
27900 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
27910 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
27920 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
27930 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
27940 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
27950 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
27960 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
27970 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
27980 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
27990 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
279a0 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
279b0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
279c0 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
279d0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
279e0 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
279f0 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
27a00 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
27a10 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
27a20 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
27a30 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
27a40 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
27a50 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
27a60 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
27a70 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
27a80 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
27a90 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
27aa0 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
27ab0 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
27ac0 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
27ad0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
27ae0 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
27af0 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
27b00 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
27b10 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
27b20 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
27b30 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
27b40 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
27b50 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
27b60 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
27b70 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
27b80 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
27b90 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
27ba0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
27bb0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
27bc0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
27bd0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
27be0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
27bf0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
27c00 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
27c10 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
27c20 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
27c30 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
27c40 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
27c50 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
27c60 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
27c70 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
27c80 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
27c90 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
27ca0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
27cb0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27cc0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
27cd0 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
27ce0 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
27cf0 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
27d00 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
27d10 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
27d20 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
27d30 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
27d40 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
27d50 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
27d60 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
27d70 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
27d80 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
27d90 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
27da0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
27db0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
27dc0 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71  ctory].*/.int sq
27dd0 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
27de0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
27df0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
27e00 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
27e10 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
27e20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
27e30 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
27e40 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
27e50 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
27e60 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
27e70 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
27e80 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
27e90 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
27ea0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
27eb0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
27ec0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
27ed0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
27ee0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
27ef0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
27f00 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
27f10 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
27f20 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
27f30 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
27f40 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
27f50 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
27f60 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
27f70 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
27f80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
27f90 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
27fa0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
27fb0 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
27fc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27fd0 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
27fe0 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
27ff0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
28000 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
28010 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
28020 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
28030 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
28040 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
28050 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
28060 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
28070 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
28080 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
28090 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
280a0 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
280b0 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
280c0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
280d0 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
280e0 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
280f0 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
28100 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
28110 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
28120 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
28130 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
28140 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
28150 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
28160 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
28170 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
28180 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
28190 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
281a0 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
281b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
281c0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
281d0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
281e0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
281f0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
28200 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
28210 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
28220 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
28230 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
28240 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
28250 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
28260 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
28270 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
28280 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
28290 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
282a0 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
282b0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
282c0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
282d0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
282e0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
282f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28300 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
28310 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
28320 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
28330 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
28340 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
28350 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
28360 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
28370 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
28380 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
28390 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
283a0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
283b0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
283c0 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
283d0 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
283e0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
283f0 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
28400 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
28410 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
28420 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
28430 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
28440 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
28450 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
28460 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
28470 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
28480 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
28490 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
284a0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
284b0 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
284c0 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
284d0 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
284e0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
284f0 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
28500 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
28510 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
28520 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
28530 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
28540 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
28550 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
28560 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
28570 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
28580 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
28590 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
285a0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
285b0 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
285c0 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
285d0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
285e0 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
285f0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
28600 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
28610 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
28620 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
28630 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
28640 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
28650 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
28660 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
28670 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
28680 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
28690 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
286a0 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
286b0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
286c0 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
286d0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
286e0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
286f0 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
28700 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
28710 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
28720 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
28730 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
28740 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
28750 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
28760 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
28770 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
28780 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
28790 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
287a0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
287b0 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
287c0 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ble..*/.const ch
287d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
287e0 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
287f0 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
28800 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
28810 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ram);.int sqlite
28820 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
28830 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
28840 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
28850 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
28860 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  t);.sqlite3_int6
28870 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  4 sqlite3_uri_in
28880 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t64(const char*,
28890 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
288a0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a  lite3_int64);...
288b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
288c0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
288d0 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48  Messages.** METH
288e0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
288f0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
28900 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20  ecent sqlite3_* 
28910 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  API call associa
28920 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61  ted with .** [da
28930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28940 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65  n] D failed, the
28950 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72  n the sqlite3_er
28960 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61  rcode(D) interfa
28970 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  ce.** returns th
28980 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
28990 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  t code] or [exte
289a0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
289b0 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50  ] for that.** AP
289c0 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68  I call..** If th
289d0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
289e0 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65  I call was succe
289f0 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74  ssful,.** then t
28a00 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
28a10 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72  from sqlite3_err
28a20 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
28a30 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ned..** ^The sql
28a40 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
28a50 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
28a60 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
28a70 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
28a80 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
28a90 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
28aa0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
28ab0 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
28ac0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
28ad0 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
28ae0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28af0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
28b00 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
28b10 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
28b20 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
28b30 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
28b40 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
28b50 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
28b60 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
28b70 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
28b80 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
28b90 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
28ba0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
28bb0 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
28bc0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
28bd0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
28be0 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
28bf0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
28c00 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
28c10 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
28c20 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
28c30 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
28c40 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
28c50 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
28c60 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
28c70 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
28c80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
28c90 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65  rstr() interface
28ca0 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67   returns the Eng
28cb0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
28cc0 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72  xt.** that descr
28cd0 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74  ibes the [result
28ce0 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38   code], as UTF-8
28cf0 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
28d00 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
28d10 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
28d20 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
28d30 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74  ally.** and must
28d40 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79   not be freed by
28d50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
28d60 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  )^..**.** When t
28d70 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
28d80 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
28d90 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
28da0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
28db0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
28dc0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
28dd0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
28de0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
28df0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
28e00 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
28e10 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
28e20 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
28e30 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
28e40 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
28e50 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
28e60 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
28e70 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
28e80 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
28e90 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
28ea0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
28eb0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
28ec0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
28ed0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
28ee0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
28ef0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
28f00 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
28f10 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
28f20 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
28f30 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
28f40 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
28f50 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
28f60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
28f70 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
28f80 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
28f90 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
28fa0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
28fb0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
28fc0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
28fd0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
28fe0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
28ff0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
29000 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
29010 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
29020 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
29030 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
29040 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
29050 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
29060 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
29070 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
29080 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
29090 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
290a0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
290b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
290c0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
290d0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
290e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
290f0 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
29100 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
29110 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
29120 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
29130 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
29140 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  rstr(int);../*.*
29150 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70  * CAPI3REF: Prep
29160 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
29170 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
29180 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
29190 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
291a0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
291b0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
291c0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
291d0 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
291e0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
291f0 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65   that.** has bee
29200 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  n compiled into 
29210 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20  binary form and 
29220 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65  is ready to be e
29230 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  valuated..**.** 
29240 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51  Think of each SQ
29250 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61  L statement as a
29260 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74   separate comput
29270 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65  er program.  The
29280 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
29290 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20   text is source 
292a0 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65  code.  A prepare
292b0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
292c0 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f  ct .** is the co
292d0 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f  mpiled object co
292e0 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73  de.  All SQL mus
292f0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69  t be converted i
29300 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65  nto a.** prepare
29310 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f  d statement befo
29320 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e  re it can be run
29330 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
29340 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70  -cycle of a prep
29350 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
29360 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f  bject usually go
29370 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  es like this:.**
29380 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
29390 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70   Create the prep
293a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
293b0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
293c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
293d0 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  )]..** <li> Bind
293e0 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61   values to [para
293f0 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
29400 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29410 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
29420 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
29430 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
29440 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
29450 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
29460 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
29470 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70  > Reset the prep
29480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
29490 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
294a0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
294b0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
294c0 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
294d0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
294e0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
294f0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
29500 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
29510 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
29520 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ol>.*/.typedef s
29530 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
29540 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
29550 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29560 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
29570 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
29580 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ite3.**.** ^(Thi
29590 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
295a0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
295b0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
295c0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
295d0 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
295e0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
295f0 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
29600 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
29610 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
29620 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
29630 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
29640 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
29650 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
29660 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
29670 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
29680 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
29690 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
296a0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
296b0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
296c0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
296d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
296e0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
296f0 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
29700 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
29710 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
29720 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
29730 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
29740 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
29750 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
29760 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
29770 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
29780 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
29790 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
297a0 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
297b0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
297c0 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
297d0 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
297e0 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
297f0 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
29800 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
29810 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
29820 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
29830 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
29840 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
29850 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
29860 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
29870 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
29880 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
29890 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
298a0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
298b0 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
298c0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
298d0 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
298e0 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
298f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
29900 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
29910 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
29920 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
29930 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
29940 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
29950 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
29960 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
29970 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
29980 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
29990 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
299a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
299b0 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
299c0 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
299d0 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
299e0 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
299f0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
29a00 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
29a10 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
29a20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
29a30 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
29a40 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
29a50 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
29a60 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
29a70 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
29a80 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
29a90 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
29aa0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
29ab0 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
29ac0 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
29ad0 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
29ae0 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
29af0 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
29b00 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
29b10 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
29b20 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
29b30 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
29b40 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
29b50 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
29b60 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
29b70 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
29b80 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
29b90 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
29ba0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
29bb0 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
29bc0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
29bd0 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
29be0 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
29bf0 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
29c00 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
29c10 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
29c20 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
29c30 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
29c40 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
29c50 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
29c60 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
29c70 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
29c80 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
29c90 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
29ca0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
29cb0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
29cc0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
29cd0 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
29ce0 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
29cf0 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
29d00 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
29d10 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
29d20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
29d30 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
29d40 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
29d50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29d60 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
29d70 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
29d80 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
29d90 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
29da0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
29db0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
29dc0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
29dd0 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
29de0 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
29df0 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
29e00 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
29e10 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
29e20 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
29e30 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
29e40 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
29e50 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
29e60 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
29e70 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
29e80 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
29e90 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
29ea0 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
29eb0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
29ec0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
29ed0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
29ee0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
29ef0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29f00 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
29f10 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
29f20 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
29f30 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
29f40 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29f50 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
29f60 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
29f70 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
29f80 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29f90 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
29fa0 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
29fb0 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
29fc0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
29fd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
29fe0 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
29ff0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
2a000 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a010 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2a020 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
2a030 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
2a040 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
2a050 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2a060 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
2a070 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
2a080 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
2a090 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
2a0a0 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
2a0b0 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
2a0c0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2a0d0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2a0e0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2a0f0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2a100 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2a110 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
2a120 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
2a130 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
2a140 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
2a150 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a160 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
2a170 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a180 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
2a190 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
2a1a0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2a1b0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
2a1c0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
2a1d0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
2a1e0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a1f0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2a200 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
2a210 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
2a220 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a230 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2a240 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
2a250 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
2a260 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
2a270 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
2a280 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2a290 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70  .  If [sqlite3_p
2a2a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
2a2b0 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  ** the equivalen
2a2c0 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63  t tries to alloc
2a2d0 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f  ate space for mo
2a2e0 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e  re than this man
2a2f0 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20  y opcodes.** in 
2a300 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65  a single prepare
2a310 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20  d statement, an 
2a320 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72  SQLITE_NOMEM err
2a330 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
2a340 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2a350 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2a360 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
2a370 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
2a380 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
2a390 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2a3a0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
2a3b0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
2a3c0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
2a3d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a3e0 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
2a3f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a400 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
2a410 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a420 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
2a430 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
2a440 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
2a450 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2a460 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2a470 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
2a480 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a490 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
2a4a0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
2a4b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
2a4c0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
2a4d0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
2a4e0 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
2a4f0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2a500 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2a510 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
2a520 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
2a530 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
2a540 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2a550 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
2a560 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
2a570 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
2a580 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
2a590 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
2a5a0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
2a5b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2a5c0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
2a5d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
2a5e0 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
2a5f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a600 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
2a610 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
2a620 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
2a630 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a640 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
2a650 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a660 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
2a670 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
2a680 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2a690 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
2a6a0 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
2a6b0 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
2a6c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a6d0 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
2a6e0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
2a6f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2a700 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
2a710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a720 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
2a730 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2a740 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
2a750 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2a760 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2a770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a780 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2a790 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2a7a0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2a7b0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2a7c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2a7d0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
2a7e0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
2a7f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2a800 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
2a810 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
2a820 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
2a830 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
2a840 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
2a850 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
2a860 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
2a870 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
2a880 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2a890 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2a8a0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
2a8b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2a8c0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2a8d0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
2a8e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2a8f0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
2a900 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
2a910 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a920 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2a930 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
2a940 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a950 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
2a960 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
2a970 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
2a980 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
2a990 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
2a9a0 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
2a9b0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
2a9c0 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
2a9d0 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
2a9e0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
2a9f0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
2aa00 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
2aa10 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
2aa20 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2aa30 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
2aa40 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
2aa50 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
2aa60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
2aa70 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
2aa80 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
2aa90 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2aaa0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2aab0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2aac0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2aad0 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
2aae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2aaf0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
2ab00 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
2ab10 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
2ab20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
2ab30 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
2ab40 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2ab50 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
2ab60 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
2ab70 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
2ab80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
2ab90 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2aba0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
2abb0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
2abc0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
2abd0 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
2abe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2abf0 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
2ac00 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
2ac10 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
2ac20 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2ac30 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
2ac40 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
2ac50 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2ac60 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
2ac70 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
2ac80 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
2ac90 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
2aca0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
2acb0 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
2acc0 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
2acd0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
2ace0 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
2acf0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
2ad00 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
2ad10 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
2ad20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
2ad30 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
2ad40 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
2ad50 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
2ad60 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
2ad70 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
2ad80 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
2ad90 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2ada0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
2adb0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
2adc0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
2add0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
2ade0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
2adf0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
2ae00 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
2ae10 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
2ae20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
2ae30 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
2ae40 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
2ae50 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
2ae60 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
2ae70 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
2ae80 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
2ae90 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
2aea0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2aeb0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
2aec0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
2aed0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
2aee0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2aef0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
2af00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2af10 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
2af20 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
2af30 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
2af40 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
2af50 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
2af60 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
2af70 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
2af80 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
2af90 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
2afa0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
2afb0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
2afc0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
2afd0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
2afe0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
2aff0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
2b000 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
2b010 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
2b020 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
2b030 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
2b040 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2b050 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
2b060 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2b070 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
2b080 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
2b090 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
2b0a0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
2b0b0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
2b0c0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
2b0d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2b0e0 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
2b0f0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2b100 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2b110 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
2b120 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
2b130 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b140 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
2b150 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
2b160 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
2b170 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
2b180 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
2b190 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
2b1a0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
2b1b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
2b1c0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
2b1d0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
2b1e0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
2b1f0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
2b200 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b210 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
2b220 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
2b230 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
2b240 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
2b250 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
2b260 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
2b270 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
2b280 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
2b290 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
2b2a0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
2b2b0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
2b2c0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
2b2d0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
2b2e0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
2b2f0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
2b300 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
2b310 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
2b320 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
2b330 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
2b340 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
2b350 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2b360 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
2b370 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
2b380 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
2b390 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
2b3a0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
2b3b0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
2b3c0 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
2b3d0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
2b3e0 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
2b3f0 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
2b400 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
2b410 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
2b420 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
2b430 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
2b440 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
2b450 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
2b460 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
2b470 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
2b480 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
2b490 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
2b4a0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
2b4b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2b4c0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
2b4d0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
2b4e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
2b4f0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
2b500 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b510 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
2b520 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
2b530 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
2b540 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
2b550 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
2b560 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
2b570 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
2b580 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
2b590 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
2b5a0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
2b5b0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
2b5c0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
2b5d0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
2b5e0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2b5f0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
2b600 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
2b610 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
2b620 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
2b630 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
2b640 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
2b650 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2b660 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
2b670 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
2b680 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
2b690 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
2b6a0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
2b6b0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
2b6c0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
2b6d0 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
2b6e0 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
2b6f0 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
2b700 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
2b710 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
2b720 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
2b730 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
2b740 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
2b750 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
2b760 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
2b770 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
2b780 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
2b790 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
2b7a0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
2b7b0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2b7c0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
2b7d0 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
2b7e0 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
2b7f0 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
2b800 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
2b810 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2b820 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
2b830 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
2b840 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
2b850 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
2b860 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2b870 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
2b880 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
2b890 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
2b8a0 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
2b8b0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2b8c0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2b8d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b8e0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2b8f0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2b900 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2b910 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2b920 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2b930 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2b940 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2b950 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2b960 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2b970 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2b980 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2b990 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2b9a0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2b9b0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2b9c0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2b9d0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2b9e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b9f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2ba00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2ba10 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2ba20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2ba30 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2ba40 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2ba50 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2ba60 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2ba70 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2ba80 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2ba90 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2baa0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2bab0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2bac0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2bad0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2bae0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2baf0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2bb00 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2bb10 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2bb20 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2bb30 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
2bb40 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2bb50 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2bb60 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2bb70 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2bb80 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2bb90 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2bba0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2bbb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2bbc0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2bbd0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2bbe0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2bbf0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2bc00 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2bc10 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2bc20 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2bc30 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2bc40 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2bc50 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2bc60 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2bc70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
2bc80 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2bc90 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2bca0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2bcb0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2bcc0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2bcd0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2bce0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2bcf0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2bd00 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2bd10 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2bd20 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2bd30 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2bd40 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2bd50 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2bd60 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2bd70 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2bd80 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2bd90 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2bda0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
2bdb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2bdc0 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
2bdd0 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
2bde0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2bdf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2be00 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  e3_sql(P) interf
2be10 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2be20 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20  inter to a copy 
2be30 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20  of the UTF-8.** 
2be40 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
2be50 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65   create [prepare
2be60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69  d statement] P i
2be70 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74  f P was.** creat
2be80 65 64 20 62 79 20 65 69 74 68 65 72 20 5b 73 71  ed by either [sq
2be90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2bea0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2beb0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2bec0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bed0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2bee0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2bef0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2bf00 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  a UTF-8.** strin
2bf10 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
2bf20 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65   SQL text of pre
2bf30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2bf40 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64  P with.** [bound
2bf50 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70   parameters] exp
2bf60 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  anded..**.** ^(F
2bf70 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2bf80 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2bf90 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 75  ent is created u
2bfa0 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20  sing the SQL.** 
2bfb0 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 62  text "SELECT $ab
2bfc0 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70  c,:xyz" and if p
2bfd0 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 73  arameter $abc is
2bfe0 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65   bound to intege
2bff0 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61  r 2345.** and pa
2c000 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20  rameter :xyz is 
2c010 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71  unbound, then sq
2c020 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c  lite3_sql() will
2c030 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f   return.** the o
2c040 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20  riginal string, 
2c050 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2c060 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65  z" but sqlite3_e
2c070 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a  xpanded_sql().**
2c080 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45   will return "SE
2c090 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e  LECT 2345,NULL".
2c0a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2c0b0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2c0c0 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ql() interface r
2c0d0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
2c0e0 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
2c0f0 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62  ry.** is availab
2c100 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  le to hold the r
2c110 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65  esult, or if the
2c120 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78   result would ex
2c130 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20  ceed the.** the 
2c140 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c  maximum string l
2c150 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64  ength determined
2c160 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
2c170 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  LIMIT_LENGTH]..*
2c180 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
2c190 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
2c1a0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
2c1b0 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74   option limits t
2c1c0 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f  he size of.** bo
2c1d0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65 78  und parameter ex
2c1e0 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20  pansions.  ^The 
2c1f0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41  [SQLITE_OMIT_TRA
2c200 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
2c210 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65  .** option cause
2c220 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  s sqlite3_expand
2c230 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61  ed_sql() to alwa
2c240 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  ys return NULL..
2c250 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  **.** ^The strin
2c260 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2c270 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20  lite3_sql(P) is 
2c280 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74  managed by SQLit
2c290 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f  e and is.** auto
2c2a0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
2c2b0 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  when the prepare
2c2c0 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66  d statement is f
2c2d0 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68  inalized..** ^Th
2c2e0 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2c2f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70  d by sqlite3_exp
2c300 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e  anded_sql(P), on
2c310 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
2c320 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20  .** is obtained 
2c330 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2c340 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74  lloc()] and must
2c350 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20   be free by the 
2c360 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62  application.** b
2c370 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  y passing it to 
2c380 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2c390 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2c3a0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
2c3b0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2c3c0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
2c3d0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71  _expanded_sql(sq
2c3e0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2c3f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2c400 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2c410 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
2c420 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
2c430 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44  tabase.** METHOD
2c440 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c450 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c460 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2c470 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
2c480 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2c490 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
2c4a0 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
2c4b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c4c0 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
2c4d0 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
2c4e0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2c4f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2c500 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2c510 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
2c520 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2c530 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
2c540 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
2c550 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
2c560 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
2c570 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
2c580 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
2c590 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
2c5a0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2c5b0 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
2c5c0 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
2c5d0 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
2c5e0 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
2c5f0 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
2c600 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
2c610 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2c620 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
2c630 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
2c640 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2c650 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
2c660 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
2c670 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
2c680 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
2c690 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2c6a0 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
2c6b0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2c6c0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
2c6d0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2c6e0 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
2c6f0 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
2c700 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
2c710 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
2c720 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
2c730 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
2c740 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
2c750 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
2c760 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
2c770 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
2c780 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
2c790 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
2c7a0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2c7b0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
2c7c0 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
2c7d0 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
2c7e0 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
2c7f0 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
2c800 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
2c810 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
2c820 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
2c830 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
2c840 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
2c850 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
2c860 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
2c870 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
2c880 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
2c890 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2c8a0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2c8b0 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
2c8c0 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
2c8d0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
2c8e0 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
2c8f0 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
2c900 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
2c910 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
2c920 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
2c930 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2c940 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
2c950 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68   on disk..** ^Th
2c960 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2c970 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66  eadonly() interf
2c980 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2c990 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e   for [BEGIN] sin
2c9a0 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65  ce.** [BEGIN] me
2c9b0 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e  rely sets intern
2c9c0 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68  al flags, but th
2c9d0 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49  e [BEGIN|BEGIN I
2c9e0 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a  MMEDIATE] and.**
2c9f0 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58   [BEGIN|BEGIN EX
2ca00 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64  CLUSIVE] command
2ca10 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64  s do touch the d
2ca20 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a  atabase and so.*
2ca30 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2ca40 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e  eadonly() return
2ca50 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73  s false for thos
2ca60 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69  e commands..*/.i
2ca70 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2ca80 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
2ca90 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2caa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cab0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
2cac0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2cad0 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
2cae0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2caf0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2cb00 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2cb10 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
2cb20 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2cb30 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
2cb40 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2cb50 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
2cb60 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
2cb70 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
2cb80 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
2cb90 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
2cba0 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f  either run to co
2cbb0 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e  mpletion (return
2cbc0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ed.** [SQLITE_DO
2cbd0 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  NE] from [sqlite
2cbe0 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a  3_step(S)]) nor.
2cbf0 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
2cc00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2cc10 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
2cc20 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2cc30 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
2cc40 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
2cc50 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
2cc60 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
2cc70 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
2cc80 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
2cc90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2cca0 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
2ccb0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2ccc0 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
2ccd0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2cce0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2ccf0 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
2cd00 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2cd10 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2cd20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
2cd30 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2cd40 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
2cd50 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
2cd60 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
2cd70 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
2cd80 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
2cd90 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
2cda0 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
2cdb0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
2cdc0 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
2cdd0 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
2cde0 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
2cdf0 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
2ce00 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
2ce10 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
2ce20 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
2ce30 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
2ce40 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2ce50 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
2ce60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ce70 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
2ce80 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
2ce90 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
2cea0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
2ceb0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
2cec0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ced0 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
2cee0 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
2cef0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2cf00 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
2cf10 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
2cf20 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
2cf30 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
2cf40 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
2cf50 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
2cf60 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
2cf70 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
2cf80 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
2cf90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2cfa0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
2cfb0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
2cfc0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
2cfd0 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
2cfe0 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
2cff0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2d000 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
2d010 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
2d020 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
2d030 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
2d040 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
2d050 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d060 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
2d070 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
2d080 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
2d090 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
2d0a0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2d0b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2d0c0 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
2d0d0 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
2d0e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
2d0f0 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
2d100 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
2d110 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
2d120 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d130 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a  3_value.  The.**
2d140 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d150 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  dup()] interface
2d160 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2d170 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20  construct a new 
2d180 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71  .** protected sq
2d190 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d  lite3_value from
2d1a0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
2d1b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2d1c0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
2d1d0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
2d1e0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
2d1f0 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
2d200 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
2d210 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
2d220 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
2d230 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
2d240 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2d250 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
2d260 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
2d270 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
2d280 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2d290 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
2d2a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2d2b0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
2d2c0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
2d2d0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
2d2e0 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
2d2f0 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
2d300 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
2d310 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
2d320 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
2d330 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
2d340 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
2d350 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2d360 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
2d370 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2d380 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
2d390 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
2d3a0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2d3b0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2d3c0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2d3d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2d3e0 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
2d3f0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
2d400 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
2d410 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
2d420 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
2d430 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
2d440 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
2d450 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
2d460 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
2d470 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2d480 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2d490 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2d4a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2d4b0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
2d4c0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
2d4d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2d4e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2d4f0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
2d500 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
2d510 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
2d520 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2d530 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2d540 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2d550 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
2d560 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
2d570 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2d580 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2d590 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d5a0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
2d5b0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
2d5c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d5d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
2d5e0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2d5f0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
2d600 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
2d610 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2d620 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
2d630 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d640 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
2d650 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
2d660 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
2d670 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
2d680 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d690 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
2d6a0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2d6b0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  t sqlite3_value 
2d6c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
2d6d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d6e0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
2d6f0 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
2d700 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
2d710 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
2d720 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
2d730 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
2d740 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
2d750 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
2d760 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
2d770 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2d780 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
2d790 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2d7a0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
2d7b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2d7c0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
2d7d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d7e0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2d7f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2d800 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
2d810 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
2d820 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
2d830 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d840 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
2d850 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
2d860 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2d870 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
2d880 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
2d890 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
2d8a0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2d8b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
2d8c0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
2d8d0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
2d8e0 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
2d8f0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2d900 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2d910 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2d920 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
2d930 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
2d940 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
2d950 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
2d960 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
2d970 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
2d980 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
2d990 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
2d9a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
2d9b0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
2d9c0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
2d9d0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
2d9e0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
2d9f0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2da00 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
2da10 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
2da20 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
2da30 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2da40 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
2da50 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
2da60 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
2da70 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
2da80 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
2da90 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
2daa0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
2dab0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
2dac0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
2dad0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
2dae0 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
2daf0 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
2db00 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
2db10 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
2db20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
2db30 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
2db40 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
2db50 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
2db60 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
2db70 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
2db80 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
2db90 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
2dba0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
2dbb0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
2dbc0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
2dbd0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
2dbe0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2dbf0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2dc00 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
2dc10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2dc20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2dc30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2dc40 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
2dc50 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
2dc60 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
2dc70 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
2dc80 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
2dc90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2dca0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
2dcb0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
2dcc0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2dcd0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2dce0 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
2dcf0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
2dd00 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
2dd10 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
2dd20 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2dd30 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
2dd40 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
2dd50 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
2dd60 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
2dd70 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2dd80 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
2dd90 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
2dda0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
2ddb0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
2ddc0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
2ddd0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
2dde0 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
2ddf0 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
2de00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2de10 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2de20 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
2de30 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
2de40 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
2de50 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
2de60 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
2de70 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
2de80 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
2de90 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
2dea0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
2deb0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
2dec0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2ded0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
2dee0 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
2def0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2df00 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2df10 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
2df20 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
2df30 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
2df40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2df50 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2df60 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2df70 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
2df80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2df90 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
2dfa0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
2dfb0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2dfc0 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
2dfd0 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
2dfe0 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
2dff0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2e000 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
2e010 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
2e020 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
2e030 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
2e040 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2e050 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2e060 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2e070 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
2e080 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
2e090 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
2e0a0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
2e0b0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
2e0c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2e0d0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
2e0e0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2e0f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2e100 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
2e110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2e120 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
2e130 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
2e140 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
2e150 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
2e160 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
2e170 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
2e180 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
2e190 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
2e1a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2e1b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2e1c0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2e1d0 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
2e1e0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2e1f0 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
2e200 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
2e210 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
2e220 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
2e230 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
2e240 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2e250 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33  t16() or sqlite3
2e260 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74  _bind_text64() t
2e270 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61  hen.** that para
2e280 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
2e290 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
2e2a0 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
2e2b0 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
2e2c0 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
2e2d0 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
2e2e0 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
2e2f0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
2e300 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
2e310 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
2e320 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
2e330 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
2e340 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2e350 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
2e360 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
2e370 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
2e380 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
2e390 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
2e3a0 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
2e3b0 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
2e3c0 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
2e3d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2e3e0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
2e3f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2e400 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20  BLOB and string 
2e410 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63  binding interfac
2e420 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72  es.** is a destr
2e430 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
2e440 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2e450 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
2e460 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
2e470 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2e480 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
2e490 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
2e4a0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2e4b0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
2e4c0 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
2e4d0 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61  l to bind API fa
2e4e0 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ils..** ^If the 
2e4f0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
2e500 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
2e510 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
2e520 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
2e530 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
2e540 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
2e550 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
2e560 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
2e570 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
2e580 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
2e590 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2e5a0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
2e5b0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
2e5c0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
2e5d0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
2e5e0 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
2e5f0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
2e600 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
2e610 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
2e620 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2e630 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
2e640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2e650 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2e660 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2e670 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  () must be one o
2e680 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  f.** [SQLITE_UTF
2e690 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2e6a0 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  6], [SQLITE_UTF1
2e6b0 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
2e6c0 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20  _UTF16LE].** to 
2e6d0 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f  specify the enco
2e6e0 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74  ding of the text
2e6f0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
2e700 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20  rameter.  If.** 
2e710 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  the sixth argume
2e720 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2e730 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e  nd_text64() is n
2e740 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
2e750 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20   allowed values 
2e760 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20  shown above, or 
2e770 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  if the text enco
2e780 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2e790 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e  t.** from the en
2e7a0 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
2e7b0 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61   by the sixth pa
2e7c0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
2e7d0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
2e7e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2e7f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2e800 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
2e810 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
2e820 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
2e830 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
2e840 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
2e850 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
2e860 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
2e870 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
2e880 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
2e890 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
2e8a0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
2e8b0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
2e8c0 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
2e8d0 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
2e8e0 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
2e8f0 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
2e900 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
2e910 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
2e920 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
2e930 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
2e940 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
2e950 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
2e960 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
2e970 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
2e980 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
2e990 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
2e9a0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
2e9b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2e9c0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
2e9d0 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
2e9e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2e9f0 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
2ea00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
2ea10 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
2ea20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
2ea30 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
2ea40 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
2ea50 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
2ea60 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
2ea70 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
2ea80 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
2ea90 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
2eaa0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
2eab0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
2eac0 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
2ead0 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
2eae0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2eaf0 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
2eb00 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
2eb10 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2eb20 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2eb30 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
2eb40 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
2eb50 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
2eb60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2eb70 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
2eb80 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
2eb90 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
2eba0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
2ebb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2ebc0 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
2ebd0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2ebe0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
2ebf0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
2ec00 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
2ec10 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
2ec20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d  SQLITE_TOOBIG] m
2ec30 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2ec40 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20   if the size of 
2ec50 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2ec60 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69  .** exceeds limi
2ec70 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73  ts imposed by [s
2ec80 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2ec90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2eca0 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  TH]) or.** [SQLI
2ecb0 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a  TE_MAX_LENGTH]..
2ecc0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
2ecd0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
2ece0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
2ecf0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
2ed00 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
2ed10 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
2ed20 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
2ed30 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
2ed40 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2ed50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ed60 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
2ed70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2ed80 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2ed90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2eda0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2edb0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
2edc0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
2edd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ede0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2edf0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
2ee00 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2ee10 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28  te3_bind_blob64(
2ee20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ee30 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2ee40 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2ee50 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2ee60 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
2ee70 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2ee80 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
2ee90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2eea0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
2eeb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2eec0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2eed0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
2eee0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2eef0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2ef00 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2ef10 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
2ef20 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
2ef30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ef40 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
2ef50 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
2ef60 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73  3_stmt*,int,cons
2ef70 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64  t char*,int,void
2ef80 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2ef90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2efa0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2efb0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2efc0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2efd0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2efe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2eff0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2f000 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
2f010 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  ar*, sqlite3_uin
2f020 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2f030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2f040 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
2f050 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
2f060 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ding);.int sqlit
2f070 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
2f080 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f090 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
2f0a0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2f0b0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2f0c0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2f0d0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69  , int, int n);.i
2f0e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2f0f0 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74  zeroblob64(sqlit
2f100 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2f110 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
2f120 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f130 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
2f140 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54  arameters.** MET
2f150 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2f160 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
2f170 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
2f180 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
2f190 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
2f1a0 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
2f1b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f1c0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
2f1d0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
2f1e0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
2f1f0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
2f200 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
2f210 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
2f220 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
2f230 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
2f240 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
2f250 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2f260 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
2f270 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
2f280 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
2f290 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2f2a0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
2f2b0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2f2c0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
2f2d0 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
2f2e0 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
2f2f0 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
2f300 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
2f310 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
2f320 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
2f330 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
2f340 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2f350 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
2f360 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
2f370 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
2f380 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
2f390 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2f3a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2f3b0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2f3c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2f3d0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2f3e0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2f3f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2f400 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2f410 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2f420 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
2f430 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2f440 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f450 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
2f460 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48  arameter.** METH
2f470 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2f480 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f490 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2f4a0 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
2f4b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2f4c0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
2f4d0 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
2f4e0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
2f4f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f500 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
2f510 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2f520 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
2f530 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2f540 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
2f550 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
2f560 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
2f570 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2f580 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2f590 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
2f5a0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
2f5b0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
2f5c0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
2f5d0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
2f5e0 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
2f5f0 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
2f600 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
2f610 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
2f620 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
2f630 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
2f640 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
2f650 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
2f660 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
2f670 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
2f680 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
2f690 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
2f6a0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2f6b0 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
2f6c0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
2f6d0 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
2f6e0 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
2f6f0 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
2f700 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
2f710 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
2f720 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
2f730 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2f740 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
2f750 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
2f760 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
2f770 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
2f780 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
2f790 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
2f7a0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
2f7b0 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
2f7c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f7d0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2f7e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2f7f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2f800 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2f810 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2f820 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2f830 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2f840 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2f850 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
2f860 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2f870 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2f880 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
2f890 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
2f8a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
2f8b0 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
2f8c0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
2f8d0 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ame.** METHOD: s
2f8e0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2f8f0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
2f900 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
2f910 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
2f920 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
2f930 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
2f940 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
2f950 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
2f960 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
2f970 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2f980 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2f990 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
2f9a0 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
2f9b0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
2f9c0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
2f9d0 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
2f9e0 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
2f9f0 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
2fa00 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
2fa10 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
2fa20 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
2fa30 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
2fa40 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
2fa50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2fa60 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2fa70 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2fa80 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2fa90 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2faa0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2fab0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2fac0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2fad0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2fae0 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  me()]..*/.int sq
2faf0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2fb00 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
2fb10 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
2fb20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
2fb30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2fb40 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
2fb50 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
2fb60 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
2fb70 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2fb80 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
2fb90 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
2fba0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
2fbb0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
2fbc0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
2fbd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2fbe0 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
2fbf0 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
2fc00 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2fc10 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
2fc20 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
2fc30 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2fc40 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
2fc50 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2fc60 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2fc70 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2fc80 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2fc90 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
2fca0 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54  esult Set.** MET
2fcb0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2fcc0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
2fcd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2fce0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2fcf0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
2fd00 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
2fd10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2fd20 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e   ^If this routin
2fd30 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61  e returns 0, tha
2fd40 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20  t means the .** 
2fd50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fd60 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20  ent] returns no 
2fd70 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
2fd80 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
2fd90 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73  ** ^However, jus
2fda0 74 20 62 65 63 61 75 73 65 20 74 68 69 73 20 72  t because this r
2fdb0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
2fdc0 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72   positive number
2fdd0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61   does not.** mea
2fde0 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f  n that one or mo
2fdf0 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20  re rows of data 
2fe00 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
2fe10 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61  .  ^A SELECT sta
2fe20 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61  tement.** will a
2fe30 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 6f 73  lways have a pos
2fe40 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f  itive sqlite3_co
2fe50 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74  lumn_count() but
2fe60 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
2fe70 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73  e.** WHERE claus
2fe80 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
2fe90 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74  d the table cont
2fea0 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65  ent, it might re
2feb0 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a  turn no rows..**
2fec0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2fed0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2fee0 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
2fef0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2ff00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2ff10 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2ff20 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
2ff30 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
2ff40 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
2ff50 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2ff60 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2ff70 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
2ff80 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
2ff90 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
2ffa0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
2ffb0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2ffc0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2ffd0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
2ffe0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
2fff0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30000 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
30010 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
30020 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
30030 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
30040 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
30050 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
30060 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
30070 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
30080 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
30090 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
300a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
300b0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
300c0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
300d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
300e0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
300f0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
30100 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
30110 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
30120 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
30130 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
30140 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
30150 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
30160 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
30170 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30180 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
30190 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
301a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
301b0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
301c0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
301d0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
301e0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
301f0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
30200 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
30210 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
30220 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
30230 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
30240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
30250 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
30260 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
30270 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
30280 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
30290 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
302a0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
302b0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
302c0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
302d0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
302e0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
302f0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
30300 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
30310 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
30320 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
30330 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
30340 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
30350 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
30360 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
30370 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
30380 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
30390 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
303a0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
303b0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
303c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
303d0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
303e0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
303f0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
30400 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
30410 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
30420 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
30430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
30440 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30450 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
30460 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
30470 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
30480 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
30490 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
304a0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
304b0 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
304c0 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
304d0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
304e0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
304f0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
30500 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
30510 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
30520 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
30530 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
30540 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
30550 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
30560 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
30570 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
30580 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
30590 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
305a0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
305b0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
305c0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
305d0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
305e0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
305f0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
30600 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
30610 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
30620 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
30630 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
30640 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
30650 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
30660 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
30670 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
30680 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
30690 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
306a0 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
306b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
306c0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
306d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
306e0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
306f0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
30700 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
30710 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
30720 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
30730 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30740 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
30750 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
30760 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
30770 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
30780 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
30790 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
307a0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
307b0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
307c0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
307d0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
307e0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
307f0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
30800 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
30810 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
30820 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
30830 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
30840 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
30850 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
30860 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
30870 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
30880 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
30890 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
308a0 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
308b0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
308c0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
308d0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
308e0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
308f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
30900 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
30910 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
30920 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
30930 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
30940 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
30950 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
30960 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
30970 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
30980 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
30990 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
309a0 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
309b0 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
309c0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
309d0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
309e0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
309f0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
30a00 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
30a10 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
30a20 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
30a30 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
30a40 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
30a50 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
30a60 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
30a70 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
30a80 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
30a90 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
30aa0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
30ab0 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
30ac0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
30ad0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
30ae0 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
30af0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
30b00 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
30b10 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
30b20 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
30b30 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
30b40 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
30b50 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
30b60 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
30b70 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
30b80 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
30b90 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
30ba0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
30bb0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
30bc0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
30bd0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
30be0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
30bf0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
30c00 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
30c10 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
30c20 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
30c30 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
30c40 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
30c50 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
30c60 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
30c70 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
30c80 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
30c90 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
30ca0 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
30cb0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
30cc0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
30cd0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
30ce0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
30cf0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
30d00 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
30d10 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
30d20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
30d30 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
30d40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
30d50 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
30d60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
30d70 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
30d80 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
30d90 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
30da0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
30db0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
30dc0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
30dd0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
30de0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
30df0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
30e00 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
30e10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30e20 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
30e30 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
30e40 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
30e50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
30e60 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
30e70 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
30e80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
30e90 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
30ea0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
30eb0 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
30ec0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30ed0 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
30ee0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
30ef0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30f00 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
30f10 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
30f20 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
30f30 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
30f40 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
30f50 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
30f60 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
30f70 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
30f80 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
30f90 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
30fa0 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
30fb0 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
30fc0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
30fd0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
30fe0 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
30ff0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
31000 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
31010 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
31020 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
31030 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
31040 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
31050 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
31060 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
31070 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
31080 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
31090 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
310a0 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
310b0 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
310c0 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
310d0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
310e0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
310f0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
31100 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
31110 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
31120 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
31130 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
31140 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
31150 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
31160 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
31170 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
31180 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
31190 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
311a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
311b0 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
311c0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
311d0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
311e0 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
311f0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
31200 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
31210 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
31220 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
31230 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
31240 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
31250 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
31260 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
31270 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
31280 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
31290 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
312a0 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
312b0 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
312c0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
312d0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
312e0 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
312f0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
31300 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
31310 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
31320 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
31330 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31340 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
31350 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
31360 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
31370 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
31380 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
31390 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
313a0 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
313b0 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
313c0 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
313d0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
313e0 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
313f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
31400 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
31410 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
31420 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31430 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
31440 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
31450 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
31460 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
31470 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
31480 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
31490 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
314a0 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
314b0 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
314c0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
314d0 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
314e0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
314f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
31500 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
31510 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
31520 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
31530 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
31540 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
31550 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
31560 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
31570 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
31580 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
31590 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
315a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
315b0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
315c0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
315d0 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
315e0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
315f0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
31600 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
31610 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
31620 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
31630 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
31640 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
31650 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
31660 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
31670 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
31680 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
31690 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
316a0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
316b0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
316c0 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
316d0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
316e0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
316f0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
31700 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
31710 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
31720 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
31730 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
31740 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
31750 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
31760 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
31770 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
31780 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
31790 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
317a0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
317b0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
317c0 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
317d0 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
317e0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
317f0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
31800 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
31810 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
31820 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
31830 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
31840 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
31850 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
31860 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
31870 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
31880 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
31890 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
318a0 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
318b0 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
318c0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
318d0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
318e0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
318f0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
31900 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
31910 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
31920 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
31930 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
31940 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
31950 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
31960 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
31970 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
31980 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
31990 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
319a0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
319b0 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
319c0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
319d0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
319e0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
319f0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
31a00 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
31a10 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
31a20 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
31a30 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
31a40 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
31a50 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
31a60 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
31a70 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
31a80 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
31a90 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
31aa0 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
31ab0 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
31ac0 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
31ad0 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
31ae0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
31af0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
31b00 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
31b10 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
31b20 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
31b30 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
31b40 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
31b50 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
31b60 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
31b70 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
31b80 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
31b90 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
31ba0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
31bb0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
31bc0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
31bd0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
31be0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
31bf0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
31c00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
31c10 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
31c20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
31c30 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
31c40 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
31c50 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
31c60 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
31c70 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
31c80 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
31c90 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
31ca0 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
31cb0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
31cc0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
31cd0 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
31ce0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31cf0 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
31d00 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
31d10 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
31d20 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
31d30 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
31d40 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
31d50 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
31d60 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
31d70 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
31d80 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
31d90 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
31da0 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
31db0 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
31dc0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
31dd0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
31de0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
31df0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
31e00 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
31e10 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
31e20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
31e30 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
31e40 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
31e50 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
31e60 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
31e70 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
31e80 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
31e90 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
31ea0 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
31eb0 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
31ec0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
31ed0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
31ee0 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
31ef0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
31f00 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
31f10 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
31f20 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
31f30 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
31f40 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
31f50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
31f60 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
31f70 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
31f80 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
31f90 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
31fa0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
31fb0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
31fc0 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
31fd0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
31fe0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
31ff0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
32000 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
32010 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
32020 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
32030 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
32040 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
32050 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36  ter [version 3.6
32060 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a  .23.1] ([dateof:
32070 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71  3.6.23.1],.** sq
32080 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
32090 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
320a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
320b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
320c0 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
320d0 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
320e0 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
320f0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
32100 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
32110 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
32120 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
32130 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
32140 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
32150 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
32160 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
32170 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
32180 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
32190 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
321a0 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
321b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
321c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
321d0 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
321e0 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
321f0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
32200 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
32210 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
32220 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
32230 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
32240 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
32250 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
32260 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
32270 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
32280 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
32290 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
322a0 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
322b0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
322c0 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
322d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
322e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
322f0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
32300 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
32310 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
32320 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
32330 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
32340 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
32350 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
32360 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
32370 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
32380 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
32390 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
323a0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
323b0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
323c0 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
323d0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
323e0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
323f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
32400 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
32410 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
32420 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
32430 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
32440 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
32450 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32460 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
32470 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
32480 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
32490 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
324a0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
324b0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
324c0 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
324d0 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
324e0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
324f0 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
32500 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
32510 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
32520 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
32530 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
32540 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d   result set.** M
32550 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
32560 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
32570 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
32580 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
32590 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
325a0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
325b0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
325c0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
325d0 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
325e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
325f0 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
32600 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
32610 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
32620 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
32630 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
32640 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
32650 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
32660 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
32670 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
32680 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
32690 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
326a0 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
326b0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
326c0 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
326d0 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
326e0 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
326f0 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
32700 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
32710 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
32720 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
32730 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
32740 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
32750 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
32760 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
32770 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
32780 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
32790 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
327a0 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
327b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
327c0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
327d0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
327e0 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
327f0 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
32800 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
32810 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
32820 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
32830 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
32840 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
32850 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
32860 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
32870 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
32880 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
32890 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
328a0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
328b0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
328c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
328d0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
328e0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
328f0 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
32900 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
32910 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
32920 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
32930 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
32940 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
32950 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
32960 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
32970 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
32980 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
32990 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
329a0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
329b0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
329c0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
329d0 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
329e0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
329f0 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
32a00 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
32a10 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
32a20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
32a30 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
32a40 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
32a50 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
32a60 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
32a70 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
32a80 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
32a90 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
32aa0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
32ab0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
32ac0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
32ad0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
32ae0 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
32af0 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
32b00 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
32b10 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
32b20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
32b30 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
32b40 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
32b50 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
32b60 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
32b70 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
32b80 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
32b90 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
32ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
32bb0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
32bc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
32bd0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
32be0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
32bf0 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
32c00 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
32c10 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
32c20 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  s functions}.** 
32c30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
32c40 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
32c50 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
32c60 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
32c70 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
32c80 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
32c90 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
32ca0 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
32cb0 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
32cc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
32cd0 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
32ce0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
32cf0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
32d00 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
32d10 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
32d20 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
32d30 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
32d40 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
32d50 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
32d60 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
32d70 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
32d80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
32d90 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
32da0 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
32db0 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
32dc0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
32dd0 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
32de0 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
32df0 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
32e00 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
32e10 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
32e20 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
32e30 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
32e40 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
32e50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32e60 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
32e70 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
32e80 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
32e90 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
32ea0 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
32eb0 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
32ec0 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
32ed0 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
32ee0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
32ef0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
32f00 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
32f10 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
32f20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
32f30 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
32f40 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
32f50 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
32f60 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
32f70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32f80 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
32f90 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
32fa0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
32fb0 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
32fc0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
32fd0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
32fe0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
32ff0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
33000 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
33010 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
33020 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
33030 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
33040 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
33050 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
33060 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
33070 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
33080 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
33090 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
330a0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
330b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
330c0 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
330d0 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
330e0 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
330f0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
33100 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
33110 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
33120 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
33130 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
33140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
33150 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
33160 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
33170 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
33180 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
33190 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
331a0 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
331b0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
331c0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
331d0 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
331e0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
331f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
33200 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
33210 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
33220 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
33230 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
33240 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
33250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
33260 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
33270 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
33280 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
33290 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
332a0 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
332b0 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
332c0 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
332d0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
332e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
332f0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
33300 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
33310 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
33320 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
33330 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
33340 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
33350 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
33360 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
33370 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
33380 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
33390 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
333a0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
333b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
333c0 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
333d0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
333e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
333f0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
33400 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
33410 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
33420 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
33430 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33440 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
33450 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
33460 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
33470 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
33480 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
33490 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
334a0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
334b0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
334c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
334d0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
334e0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
334f0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
33500 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
33510 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
33520 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
33530 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
33540 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
33550 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
33560 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
33570 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
33580 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
33590 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
335a0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
335b0 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
335c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
335d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
335e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
335f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
33600 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
33610 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
33620 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
33630 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
33640 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
33650 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
33660 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
33670 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
33680 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
33690 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
336a0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
336b0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
336c0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
336d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
336e0 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
336f0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
33700 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
33710 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
33720 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
33730 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
33740 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
33750 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
33760 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
33770 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
33780 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
33790 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
337a0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
337b0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
337c0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
337d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
337e0 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
337f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
33800 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
33810 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
33820 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
33830 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
33840 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
33850 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
33860 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
33870 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33880 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
33890 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
338a0 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
338b0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
338c0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
338d0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
338e0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
338f0 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
33900 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
33910 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
33920 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
33930 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
33940 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
33950 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
33960 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
33970 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
33980 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
33990 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
339a0 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
339b0 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
339c0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
339d0 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20  <b>Warning:</b> 
339e0 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
339f0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
33a00 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
33a10 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
33a20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33a30 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49  alue] object.  I
33a40 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65  n a multithreade
33a50 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a  d environment,.*
33a60 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  * an unprotected
33a70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
33a80 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62  bject may only b
33a90 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69  e used safely wi
33aa0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  th.** [sqlite3_b
33ab0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
33ac0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33ad0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
33ae0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
33af0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
33b00 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
33b10 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
33b20 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
33b30 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
33b40 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
33b50 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
33b60 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
33b70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
33b80 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
33b90 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
33ba0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
33bb0 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20  e_bytes()], the 
33bc0 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20  behavior is not 
33bd0 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a  threadsafe..**.*
33be0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
33bf0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
33c00 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
33c10 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
33c20 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
33c30 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
33c40 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
33c50 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
33c60 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
33c70 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
33c80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
33c90 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
33ca0 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
33cb0 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
33cc0 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
33cd0 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
33ce0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
33cf0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
33d00 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
33d10 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
33d20 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
33d30 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
33d40 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
33d50 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
33d60 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
33d70 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
33d80 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
33d90 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
33da0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
33db0 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
33dc0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
33dd0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
33de0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
33df0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
33e00 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
33e10 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
33e20 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
33e30 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
33e40 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
33e50 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
33e60 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
33e70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
33e80 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
33e90 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
33ea0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
33eb0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
33ec0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
33ed0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
33ee0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
33ef0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
33f00 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
33f10 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
33f20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
33f30 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
33f40 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
33f50 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
33f60 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
33f70 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
33f80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
33f90 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
33fa0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
33fb0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
33fc0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
33fd0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
33fe0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
33ff0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
34000 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
34010 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
34020 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
34030 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
34040 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
34050 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
34060 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
34070 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
34080 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
34090 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
340a0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
340b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
340c0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
340d0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
340e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
340f0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
34100 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
34110 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
34120 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
34130 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
34140 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
34150 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
34160 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
34170 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
34180 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
34190 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
341a0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
341b0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
341c0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
341d0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
341e0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
341f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
34200 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
34210 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
34220 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
34230 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
34240 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
34250 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
34260 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
34270 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
34280 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
34290 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
342a0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
342b0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
342c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
342d0 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
342e0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
342f0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
34300 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
34310 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
34320 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
34330 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
34340 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
34350 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
34360 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
34370 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
34380 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34390 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
343a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
343b0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
343c0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
343d0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
343e0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
343f0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
34400 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
34410 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
34420 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
34430 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
34440 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
34450 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
34460 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
34470 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
34480 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
34490 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
344a0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
344b0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
344c0 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
344d0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
344e0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
344f0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
34500 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
34510 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
34520 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
34530 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
34540 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
34550 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
34560 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
34570 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
34580 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
34590 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
345a0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
345b0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
345c0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
345d0 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
345e0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
345f0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
34600 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
34610 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
34620 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
34630 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74  fest policy is t
34640 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
34650 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
34660 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
34670 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
34680 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
34690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
346a0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
346b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
346c0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
346d0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
346e0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
346f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
34700 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
34710 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
34720 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
34730 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
34740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34750 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
34760 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
34770 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
34780 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
34790 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
347a0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
347b0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
347c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
347d0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
347e0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
347f0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
34800 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
34810 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
34820 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
34830 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
34840 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
34850 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
34860 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
34870 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
34880 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
34890 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
348a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
348b0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
348c0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
348d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
348e0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
348f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
34900 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
34910 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
34920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34930 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
34940 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
34950 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
34960 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
34970 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
34980 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
34990 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
349a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
349b0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
349c0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
349d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
349e0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
349f0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
34a00 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
34a10 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
34a20 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
34a30 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e  cally.  Do <em>n
34a40 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65  ot</em> pass the
34a50 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
34a60 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
34a70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
34a80 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
34a90 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
34aa0 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
34ab0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
34ac0 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
34ad0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
34ae0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
34af0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
34b00 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
34b10 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
34b20 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
34b30 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
34b40 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
34b50 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
34b60 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
34b70 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
34b80 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
34b90 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
34ba0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
34bb0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
34bc0 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
34bd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
34be0 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
34bf0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
34c00 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
34c10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
34c20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
34c30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
34c40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
34c50 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
34c60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
34c70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34c80 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
34c90 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
34ca0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
34cb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
34cc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
34cd0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
34ce0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
34cf0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
34d00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34d10 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
34d20 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
34d30 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
34d40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
34d50 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
34d60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
34d70 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
34d80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
34d90 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
34da0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
34db0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
34dc0 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
34dd0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
34de0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
34df0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
34e00 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
34e10 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
34e20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34e30 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
34e40 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
34e50 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ect.** DESTRUCTO
34e60 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
34e70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34e80 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
34e90 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
34ea0 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
34eb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34ec0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
34ed0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
34ee0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
34ef0 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
34f00 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
34f10 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
34f20 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
34f30 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
34f40 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
34f50 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
34f60 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
34f70 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
34f80 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
34f90 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
34fa0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
34fb0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
34fc0 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
34fd0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
34fe0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
34ff0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
35000 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35010 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
35020 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
35030 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
35040 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
35050 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
35060 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35070 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
35080 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
35090 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
350a0 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
350b0 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
350c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
350d0 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
350e0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
350f0 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
35100 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
35110 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
35120 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
35130 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
35140 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
35150 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
35160 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
35170 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
35180 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
35190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
351a0 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
351b0 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
351c0 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
351d0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
351e0 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
351f0 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
35200 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
35210 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
35220 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
35230 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
35240 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
35250 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
35260 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
35270 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
35280 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
35290 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
352a0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
352b0 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
352c0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
352d0 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
352e0 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
352f0 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ption..*/.int sq
35300 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
35310 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
35320 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
35330 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
35340 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
35350 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f   Object.** METHO
35360 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
35370 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
35380 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
35390 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
353a0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
353b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
353c0 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
353d0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
353e0 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
353f0 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
35400 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
35410 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
35420 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
35430 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
35440 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
35450 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
35460 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
35470 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
35480 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
35490 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
354a0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
354b0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
354c0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
354d0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
354e0 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
354f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
35500 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
35510 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
35520 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
35530 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
35540 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
35550 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
35560 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
35570 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
35580 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
35590 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
355a0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
355b0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
355c0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
355d0 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
355e0 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
355f0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
35600 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
35610 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
35620 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
35630 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
35640 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
35650 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
35660 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35670 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
35680 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
35690 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
356a0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
356b0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
356c0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
356d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
356e0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
356f0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
35700 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
35710 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
35720 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
35730 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
35740 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
35750 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35760 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
35770 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
35780 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
35790 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
357a0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
357b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
357c0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
357d0 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
357e0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
357f0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
35800 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
35810 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
35820 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
35830 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
35840 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
35850 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
35860 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
35870 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
35880 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
35890 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
358a0 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
358b0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
358c0 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
358d0 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
358e0 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
358f0 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
35900 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
35910 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
35920 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
35930 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
35940 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
35950 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
35960 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  r.** the second 
35970 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
35980 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
35990 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
359a0 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
359b0 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
359c0 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
359d0 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
359e0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
359f0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
35a00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
35a10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
35a20 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35a30 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
35a40 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
35a50 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
35a60 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
35a70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
35a80 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
35a90 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
35aa0 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
35ab0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
35ac0 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
35ad0 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
35ae0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
35af0 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
35b00 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
35b10 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
35b20 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
35b30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
35b40 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
35b50 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
35b60 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
35b70 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
35b80 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
35b90 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
35ba0 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
35bb0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
35bc0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
35bd0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
35be0 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
35bf0 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
35c00 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
35c10 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
35c20 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
35c30 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
35c40 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
35c50 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
35c60 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
35c70 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
35c80 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
35c90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
35ca0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
35cb0 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
35cc0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
35cd0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
35ce0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
35cf0 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
35d00 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
35d10 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
35d20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
35d30 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
35d40 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
35d50 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
35d60 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
35d70 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
35d80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
35d90 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
35da0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
35db0 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
35dc0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
35dd0 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
35de0 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
35df0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
35e00 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
35e10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
35e20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
35e30 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
35e40 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
35e50 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
35e60 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
35e70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
35e80 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
35e90 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65  parameters.  The
35ea0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
35eb0 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72  uld set this par
35ec0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51  ameter to.** [SQ
35ed0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66  LITE_UTF16LE] if
35ee0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
35ef0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
35f00 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  okes .** [sqlite
35f10 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
35f20 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
35f30 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
35f40 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69  6BE] if the.** i
35f50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
35f60 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76  vokes [sqlite3_v
35f70 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d  alue_text16be()]
35f80 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
35f90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
35fa0 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76  6] if [sqlite3_v
35fb0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69  alue_text16()] i
35fc0 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49  s used, or [SQLI
35fd0 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65  TE_UTF8].** othe
35fe0 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d  rwise.  ^The sam
35ff0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d  e SQL function m
36000 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
36010 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
36020 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65  using.** differe
36030 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78  nt preferred tex
36040 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74  t encodings, wit
36050 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c  h different impl
36060 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a  ementations for.
36070 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67  ** each encoding
36080 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
36090 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
360a0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
360b0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
360c0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
360d0 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
360e0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
360f0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
36100 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
36110 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rsion..**.** ^Th
36120 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
36130 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c  er may optionall
36140 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b  y be ORed with [
36150 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
36160 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e  STIC].** to sign
36170 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63  al that the func
36180 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73  tion will always
36190 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
361a0 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a   result given.**
361b0 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
361c0 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65   within a single
361d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
361e0 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69   Most SQL functi
361f0 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72  ons are.** deter
36200 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62  ministic.  The b
36210 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28  uilt-in [random(
36220 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  )] SQL function 
36230 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
36240 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74   a.** function t
36250 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72  hat is not deter
36260 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53  ministic.  The S
36270 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e  QLite query plan
36280 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  ner is able to.*
36290 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69  * perform additi
362a0 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f  onal optimizatio
362b0 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73  ns on determinis
362c0 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73  tic functions, s
362d0 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20  o use.** of the 
362e0 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
362f0 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72  ISTIC] flag is r
36300 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65  ecommended where
36310 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a   possible..**.**
36320 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
36330 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
36340 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
36350 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
36360 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
36370 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
36380 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
36390 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
363a0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
363b0 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
363c0 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
363d0 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
363e0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
363f0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
36400 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
36410 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
36420 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
36430 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
36440 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
36450 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
36460 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
36470 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
36480 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
36490 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
364a0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
364b0 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
364c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
364d0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
364e0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
364f0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
36500 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
36510 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
36520 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
36530 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
36540 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
36550 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
36560 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
36570 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
36580 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
36590 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
365a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
365b0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
365c0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
365d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
365e0 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
365f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
36600 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
36610 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
36620 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
36630 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
36640 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
36650 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
36660 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
36670 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
36680 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
36690 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
366a0 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
366b0 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
366c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
366d0 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
366e0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
366f0 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
36700 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
36710 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
36720 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
36730 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
36740 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
36750 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
36760 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
36770 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
36780 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
36790 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
367a0 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
367b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
367c0 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
367d0 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
367e0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
367f0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
36800 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
36810 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
36820 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
36830 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
36840 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
36850 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
36860 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
36870 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
36880 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
36890 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
368a0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
368b0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
368c0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
368d0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
368e0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
368f0 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
36900 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
36910 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
36920 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
36930 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
36940 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
36950 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
36960 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
36970 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
36980 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
36990 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
369a0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
369b0 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
369c0 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
369d0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
369e0 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
369f0 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
36a00 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
36a10 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
36a20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
36a30 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
36a40 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
36a50 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
36a60 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
36a70 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
36a80 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
36a90 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
36aa0 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
36ab0 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
36ac0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
36ad0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
36ae0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
36af0 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
36b00 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
36b10 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
36b20 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
36b30 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
36b40 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
36b50 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36b60 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
36b70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36b80 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
36b90 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
36ba0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
36bb0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
36bc0 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
36bd0 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
36be0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
36bf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
36c00 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
36c10 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
36c20 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
36c30 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
36c40 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
36c50 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
36c60 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
36c70 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
36c80 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
36c90 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
36ca0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
36cb0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
36cc0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
36cd0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
36ce0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
36cf0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
36d00 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
36d10 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
36d20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
36d30 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
36d40 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
36d50 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
36d60 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36d70 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
36d80 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
36d90 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
36da0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
36db0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
36dc0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
36dd0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
36de0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
36df0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
36e00 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
36e10 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
36e20 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
36e30 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
36e40 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
36e50 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
36e60 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
36e70 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
36e80 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
36e90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
36ea0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
36eb0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
36ec0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
36ed0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
36ee0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
36ef0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
36f00 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
36f10 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
36f20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
36f30 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
36f40 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
36f50 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
36f60 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
36f70 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
36f80 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
36f90 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
36fa0 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
36fb0 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
36fc0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
36fd0 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
36fe0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
36ff0 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
37000 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
37010 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
37020 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
37030 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   1    /* IMP: R-
37040 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23  37514-35566 */.#
37050 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
37060 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20  F16LE        2  
37070 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37    /* IMP: R-0337
37080 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69  1-37637 */.#defi
37090 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
370a0 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a  E        3    /*
370b0 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34   IMP: R-51971-34
370c0 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  154 */.#define S
370d0 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
370e0 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
370f0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
37100 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
37110 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
37120 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72      5    /* Depr
37130 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e  ecated */.#defin
37140 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
37150 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
37160 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37170 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
37180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37190 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73  : Function Flags
371a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
371b0 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52  stants may be OR
371c0 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68  ed together with
371d0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
371e0 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65  _UTF8 | preferre
371f0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  d text encoding]
37200 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61   as the fourth a
37210 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
37220 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
37230 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  nction()], [sqli
37240 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
37250 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
37260 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37270 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  function_v2()]..
37280 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
37290 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20  E_DETERMINISTIC 
372a0 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20     0x800../*.** 
372b0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
372c0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
372d0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
372e0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
372f0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
37300 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
37310 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
37320 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
37330 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
37340 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
37350 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
37360 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
37370 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
37380 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
37390 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
373a0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
373b0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
373c0 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61  encourage progra
373d0 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a  mmers to avoid.*
373e0 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
373f0 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65  s, we will not e
37400 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79  xplain what they
37410 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
37420 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
37430 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45  ECATED.SQLITE_DE
37440 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
37450 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37460 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
37470 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  text*);.SQLITE_D
37480 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
37490 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
374a0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
374b0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
374c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
374d0 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
374e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
374f0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
37500 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
37510 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
37520 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
37530 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
37540 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
37550 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
37560 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
37570 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
37580 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
37590 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
375a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
375b0 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
375c0 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73           void*,s
375d0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
375e0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
375f0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
37600 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d   SQL Values.** M
37610 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76  ETHOD: sqlite3_v
37620 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  alue.**.** The C
37630 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
37640 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
37650 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
37660 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
37670 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
37680 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
37690 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
376a0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
376b0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
376c0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20  n or aggregate. 
376d0 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e   .**.** The xFun
376e0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
376f0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
37700 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
37710 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
37720 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
37730 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
37740 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
37750 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
37760 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
37770 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
37780 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
37790 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
377a0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
377b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
377c0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
377d0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
377e0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
377f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
37800 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
37810 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
37820 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37830 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
37840 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37850 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
37860 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
37870 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
37880 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
37890 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
378a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
378b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
378c0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
378d0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
378e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
378f0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
37900 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
37910 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
37920 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
37930 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
37940 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
37950 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
37960 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
37970 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
37980 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
37990 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
379a0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
379b0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
379c0 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75  t that these rou
379d0 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
379e0 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
379f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37a00 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
37a10 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
37a20 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
37a30 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
37a40 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
37a50 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
37a60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37a70 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
37a80 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
37a90 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
37aa0 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
37ab0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
37ac0 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
37ad0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
37ae0 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
37af0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37b00 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
37b10 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
37b20 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
37b30 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
37b40 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
37b50 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
37b60 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
37b70 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
37b80 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
37b90 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
37ba0 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
37bb0 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
37bc0 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
37bd0 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
37be0 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
37bf0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
37c00 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
37c10 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
37c20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
37c30 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
37c40 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
37c50 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
37c60 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
37c70 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
37c80 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
37c90 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
37ca0 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
37cb0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
37cc0 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
37cd0 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
37ce0 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
37cf0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
37d00 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
37d10 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
37d20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
37d30 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
37d40 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
37d50 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
37d60 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
37d70 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
37d80 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
37d90 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
37da0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
37db0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
37dc0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
37dd0 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
37de0 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
37df0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
37e00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37e10 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
37e20 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
37e30 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
37e40 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
37e50 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
37e60 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
37e70 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
37e80 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
37e90 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
37ea0 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
37eb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
37ec0 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
37ed0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
37ee0 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
37ef0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
37f00 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
37f10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
37f20 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
37f30 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
37f40 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
37f50 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
37f60 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
37f70 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
37f80 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
37f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37fa0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
37fb0 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
37fc0 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
37fd0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
37fe0 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
37ff0 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 2a  _value*);.void *
38000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 70 6f  sqlite3_value_po
38010 69 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 76 61  inter(sqlite3_va
38020 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
38030 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
38040 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
38050 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
38060 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
38070 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
38080 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
38090 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
380a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
380b0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
380c0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
380d0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
380e0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
380f0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
38100 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
38110 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
38120 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
38130 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
38140 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
38150 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38160 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53  F: Finding The S
38170 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61  ubtype Of SQL Va
38180 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
38190 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
381a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
381b0 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29  value_subtype(V)
381c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
381d0 73 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f  s the subtype fo
381e0 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61  r.** an [applica
381f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
38200 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d   function] argum
38210 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 74  ent V.  The subt
38220 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ype.** informati
38230 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
38240 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64  o pass a limited
38250 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
38260 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53  xt from.** one S
38270 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61  QL function to a
38280 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 65  nother.  Use the
38290 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
382a0 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72  _subtype()].** r
382b0 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68  outine to set th
382c0 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 68  e subtype for th
382d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
382e0 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  f an SQL functio
382f0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
38300 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20  makes no use of 
38310 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20  subtype itself. 
38320 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65   It merely passe
38330 73 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a  s the subtype.**
38340 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74   from the result
38350 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61   of one [applica
38360 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
38370 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20   function] into 
38380 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20  the.** input of 
38390 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69  another..*/.unsi
383a0 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33  gned int sqlite3
383b0 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73  _value_subtype(s
383c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
383d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
383e0 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53   Copy And Free S
383f0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
38400 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
38410 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ue.**.** ^The sq
38420 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
38430 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  V) interface mak
38440 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
38450 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
38460 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64  .** object D and
38470 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
38480 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e  er to that copy.
38490 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
384a0 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a  value] returned.
384b0 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74  ** is a [protect
384c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
384d0 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66  ] object even if
384e0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f   the input is no
384f0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
38500 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20  e3_value_dup(V) 
38510 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
38520 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e  s NULL if V is N
38530 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d  ULL or if a.** m
38540 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
38550 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54   fails..**.** ^T
38560 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
38570 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61  _free(V) interfa
38580 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c  ce frees an [sql
38590 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
385a0 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ct.** previously
385b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
385c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
385d0 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20  p()].  ^If V is 
385e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
385f0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76  * then sqlite3_v
38600 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20  alue_free(V) is 
38610 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
38620 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ..*/.sqlite3_val
38630 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ue *sqlite3_valu
38640 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69  e_dup(const sqli
38650 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
38660 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
38670 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  free(sqlite3_val
38680 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
38690 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
386a0 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
386b0 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48   Context.** METH
386c0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
386d0 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
386e0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
386f0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
38700 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
38710 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
38720 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
38730 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
38740 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
38750 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
38760 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
38770 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
38780 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
38790 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
387a0 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
387b0 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
387c0 2a 2a 20 61 6c 6c 6f