/ Hex Artifact Content
Login

Artifact ff59423b65e5573b3abdf65c8a437ceaef93eb69:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e  -in (UTC) and an
1090: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
10a0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
10b0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
10c0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
10d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
10e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
10f0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1100: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
1110: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
1120: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1130: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
1140: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
1150: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
1160: 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52  ON        "--VER
1170: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  S--".#define SQL
1180: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1190: 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  ER --VERSION-NUM
11a0: 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 20 53 51  BER--.#define SQ
11b0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
11c0: 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 2d 49 44      "--SOURCE-ID
11d0: 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  --"../*.** CAPI3
11e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
11f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
1200: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  mbers.** KEYWORD
1210: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
1220: 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  on sqlite3_sourc
1230: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
1240: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
1250: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
1260: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
1270: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
1280: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1290: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
12a0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
12b0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
12c0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
12d0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
12e0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
12f0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1300: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
1310: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
1320: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
1330: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
1340: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1350: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1360: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
1370: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1380: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
1390: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
13a0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
13b0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
13c0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
13d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
13e0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
13f0: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
1400: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
1410: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
1420: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
1430: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
1440: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1450: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
1460: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
1470: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
1480: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1490: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
14a0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
14b0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
14c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
14d0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
14e0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
14f0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1500: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1510: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1520: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
1530: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
1540: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
1550: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
1560: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1570: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
1580: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1590: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
15a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
15b0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
15c0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
15d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
15e0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
15f0: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
1600: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
1610: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
1620: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
1630: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
1660: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
1670: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1680: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
1690: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
16a0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
16b0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
16c0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
16d0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
16e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
16f0: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
1700: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
1710: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
1720: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
1730: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1740: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1750: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
1760: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1770: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
1780: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
1790: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
17a0: 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
17b0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
17c0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e  3_version[];.con
17d0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
17e0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
17f0: 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1800: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1810: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
1820: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1830: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  mber(void);../*.
1840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1850: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f  -Time Library Co
1860: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  mpilation Option
1870: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a  s Diagnostics.**
1880: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1890: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
18a0: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  sed() function r
18b0: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a  eturns 0 or 1 .*
18c0: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65  * indicating whe
18d0: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69  ther the specifi
18e0: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65  ed option was de
18f0: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d  fined at .** com
1900: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65  pile time.  ^The
1910: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20   SQLITE_ prefix 
1920: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66  may be omitted f
1930: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69  rom the .** opti
1940: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74  on name passed t
1950: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  o sqlite3_compil
1960: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20  eoption_used(). 
1970: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f  on_get() functio
19a0: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69  n allows iterati
19b0: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c  ng.** over the l
19c0: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74  ist of options t
19d0: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64  hat were defined
19e0: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
19f0: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67   by.** returning
1a00: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c   the N-th compil
1a10: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74  e time option st
1a20: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20  ring.  ^If N is 
1a30: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a  out of range,.**
1a40: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1a50: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74  option_get() ret
1a60: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1a70: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ter.  ^The SQLIT
1a80: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73  E_ .** prefix is
1a90: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e   omitted from an
1aa0: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  y strings return
1ab0: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1ad0: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75  get()..**.** ^Su
1ae0: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69  pport for the di
1af0: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f  agnostic functio
1b00: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ns sqlite3_compi
1b10: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a  leoption_used().
1b20: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b40: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  () may be omitte
1b50: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20  d by specifying 
1b60: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1b70: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1b80: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e  ON_DIAGS] option
1b90: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
1ba0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1bb0: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  : SQL functions 
1bc0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1bd0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e  ption_used()] an
1be0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  d.** [sqlite_com
1bf0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1c00: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69  ] and the [compi
1c10: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d  le_options pragm
1c20: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  a]..*/.#ifndef S
1c30: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
1c40: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 69  LEOPTION_DIAGS.i
1c50: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nt sqlite3_compi
1c60: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
1c70: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
1c80: 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  me);.const char 
1c90: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1ca0: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1cb0: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
1cc0: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
1cd0: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
1ce0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
1cf0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
1d00: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1d10: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
1d20: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
1d30: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
1d40: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1d50: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
1d60: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1d70: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1d80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1d90: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1da0: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1db0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1dc0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1dd0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1de0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1df0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1e00: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1e10: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1e20: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1e30: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1e40: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1e50: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1e60: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1e70: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1e80: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1e90: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1ea0: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1eb0: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1ec0: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1ed0: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1ee0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1ef0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1f00: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1f10: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1f20: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1f30: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1f40: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1f50: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1f60: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1f70: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1f80: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1f90: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1fa0: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1fb0: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1fc0: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1fd0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1fe0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1ff0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
2020: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
2030: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
2040: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
2050: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
2060: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
2070: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
2080: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
2090: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
20a0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
20b0: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
20c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
20d0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
20e0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
20f0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
2100: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
2110: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2120: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
2130: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2140: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
2150: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
2160: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
2170: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2180: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2190: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
21a0: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
21b0: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
21c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
21d0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
21e0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
21f0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2200: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2210: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
2220: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
2230: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
2240: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2250: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2260: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2270: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2280: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2290: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
22a0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
22b0: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
22c0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
22d0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
22e0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
22f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2300: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2310: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
2320: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
2330: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2340: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2350: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2360: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2370: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2380: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2390: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
23a0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
23b0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23c0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
23d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23e0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
23f0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2400: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2410: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2420: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
2430: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
2440: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
2450: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
2460: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
2470: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2480: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2490: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
24a0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
24b0: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
24c0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
24d0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
24e0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
24f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2500: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2510: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
2520: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2530: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
2540: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
2550: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
2560: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
2570: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2580: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2590: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
25a0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
25b0: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
25c0: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
25d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
25f0: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2600: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2610: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
2620: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
2630: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
2640: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
2650: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
2660: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2670: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2680: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2690: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
26a0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
26b0: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
26c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
26d0: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
26e0: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
26f0: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2700: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2710: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
2720: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
2730: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
2740: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
2750: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
2760: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2770: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2780: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2790: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
27a0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
27b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
27c0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
27d0: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
27e0: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
27f0: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2800: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2810: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2820: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
2830: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
2840: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
2850: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
2860: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
2870: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2880: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2890: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
28a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
28b0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
28c0: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
28d0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
28e0: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
28f0: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2900: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2910: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
2920: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2930: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
2940: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
2950: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 23 20  sqlite_int64;.# 
2960: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e  ifdef SQLITE_UIN
2970: 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74 79 70  T64_TYPE.    typ
2980: 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e 54  edef SQLITE_UINT
2990: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
29a0: 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20 20 0a  int64;.# else  .
29b0: 20 20 20 20 74 79 70 65 64 65 66 20 75 6e 73 69      typedef unsi
29c0: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
29d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
29e0: 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a 23 65  nt64;.# endif.#e
29f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2a00: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2a10: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2a20: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2a30: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2a40: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2a50: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2a60: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2a70: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2a80: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2a90: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2aa0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2ab0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
2ac0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
2ad0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
2ae0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
2af0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2b00: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2b10: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2b20: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2b30: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2b40: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2b50: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2b60: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2b70: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2b80: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2b90: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2ba0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2bb0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2bc0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2bd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2be0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2bf0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2c00: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2c10: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2c20: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2c30: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2c40: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2c50: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2c60: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2c70: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2c80: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2c90: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2ca0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2cb0: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2cc0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2cd0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2ce0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2cf0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2d00: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2d10: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2d20: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2d30: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d50: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2d60: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2d70: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2d80: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2d90: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2da0: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2db0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2dc0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2dd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2de0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2df0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2e00: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2e10: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2e20: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2e30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2e40: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2e50: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2e60: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2e70: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2e80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2e90: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2ea0: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2eb0: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2ec0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2ed0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2ee0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2ef0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2f00: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2f10: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2f20: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2f30: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2f40: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2f50: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2f60: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2f70: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2f80: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2f90: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2fa0: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2fb0: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2fc0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2fd0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2fe0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ff0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
3000: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
3010: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
3020: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3030: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
3040: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
3050: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
3060: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
3070: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
3080: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
3090: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
30a0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
30b0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
30c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
30d0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
30e0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
30f0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
3100: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
3110: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3120: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3130: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3140: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3150: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3160: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3170: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3180: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3190: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
31a0: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
31b0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
31c0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
31d0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
31e0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
31f0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
3200: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
3210: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3220: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3230: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3240: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3250: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3260: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3270: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3280: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3290: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
32a0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
32b0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
32c0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
32d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
32e0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
32f0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
3300: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
3310: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3320: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3330: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3340: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3350: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3360: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3370: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3380: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3390: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
33a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
33b0: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
33c0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
33d0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
33e0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
33f0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
3400: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
3410: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3420: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3430: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3440: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3450: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3460: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3470: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3480: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3490: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
34a0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
34b0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
34c0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
34d0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
34e0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
34f0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
3500: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
3510: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3520: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3530: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3540: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3550: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3560: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3570: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3580: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3590: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
35a0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
35b0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
35c0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
35d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
35e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
35f0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
3600: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3610: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3620: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3630: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3640: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3650: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3660: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3670: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3680: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3690: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
36a0: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
36b0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
36c0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
36d0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
36e0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
36f0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
3700: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3710: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3730: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3740: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3750: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3760: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3770: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3780: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3790: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
37a0: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
37b0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
37c0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
37d0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
37e0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
37f0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
3800: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3810: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3820: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3830: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3840: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3850: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3860: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3870: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3880: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3890: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
38a0: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
38b0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
38c0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
38d0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
38e0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
38f0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
3900: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3910: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3920: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3940: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3950: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3960: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3970: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3980: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3990: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
39a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39b0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39c0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
39d0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
39e0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
39f0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
3a00: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3a10: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3a20: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3a30: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3a40: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3a50: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3a60: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3a70: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3a80: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3a90: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3aa0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3ab0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
3ac0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
3ad0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  eter of.** sqlit
3ae0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
3af0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
3b00: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
3b10: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3b20: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3b30: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3b40: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3b50: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3b60: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3b70: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3b80: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3b90: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3ba0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3bb0: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3bc0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3bd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3be0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3bf0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3c00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3c10: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3c20: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3c30: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3c40: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3c50: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3c60: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3c70: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3c80: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3c90: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3ca0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3cb0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3cc0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3cd0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3ce0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3cf0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3d00: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3d10: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3d20: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3d30: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3d40: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3d50: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3d70: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3d80: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3d90: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3da0: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3db0: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3dc0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3dd0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3de0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3df0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e00: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3e10: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3e20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e30: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3e40: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3e50: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e60: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3e70: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3e80: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3e90: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3ea0: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3eb0: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3ec0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3ed0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3ee0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3ef0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3f00: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f10: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3f20: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3f30: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3f40: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3f50: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3f60: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3f70: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3f80: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3f90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3fa0: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3fb0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3fc0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3fd0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3fe0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3ff0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4000: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
4010: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
4020: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
4040: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
4050: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
4060: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
4070: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4080: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
4090: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
40a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
40b0: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
40c0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
40d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
40e0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
40f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4100: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
4110: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4120: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4130: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4140: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4150: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4160: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4170: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4180: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4190: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
41a0: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
41b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
41c0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
41f0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
4200: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
4210: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
4240: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
4250: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
4260: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4270: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4280: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4290: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
42c0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
42d0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
42e0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
4310: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4320: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
4330: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
4340: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4350: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
4360: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4370: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4380: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4390: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
43a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
43b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
43c0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
43d0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
43e0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
43f0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
4400: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
4410: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4420: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
4430: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
4440: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4450: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4460: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4470: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4480: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4490: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
44a0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
44b0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
44c0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
44d0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
44e0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
44f0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4510: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4520: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4530: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4540: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4550: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4560: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4570: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4590: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
45a0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
45b0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
45c0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
45d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
45e0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
45f0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4600: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4620: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4630: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4640: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4650: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4660: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4670: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4680: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
46a0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
46b0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
46c0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
46d0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
46e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
46f0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4700: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4710: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4720: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4730: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4740: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4750: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4760: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4770: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4780: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4790: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
47a0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
47b0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
47c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
47d0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
47e0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
47f0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4800: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4820: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4830: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4840: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4850: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4870: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4880: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4890: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
48a0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
48b0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
48c0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
48d0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
48e0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
48f0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4900: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4910: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4920: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4930: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4940: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4950: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4980: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4990: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
49a0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
49b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
49c0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
49d0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
49e0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
49f0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4a00: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4a10: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4a20: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4a40: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4a50: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4a60: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4a80: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4a90: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4aa0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4ab0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4ad0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4ae0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4af0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4b00: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4b10: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4b20: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4b30: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4b40: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4b50: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4b60: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4b70: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4b80: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ba0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4bb0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4bc0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4bd0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4be0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4bf0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4c00: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4c10: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c30: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4c40: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4c50: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4c60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4c70: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4c80: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4c90: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4ca0: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4cc0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4cd0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ce0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4cf0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4d00: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4d10: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4d20: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4d30: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4d40: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4d50: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4d60: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4d70: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4d80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4d90: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4da0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4db0: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4dc0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4dd0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4de0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4df0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4e00: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4e10: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4e20: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4e30: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4e40: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4e50: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4e60: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4e70: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4e80: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4e90: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4ea0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4eb0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4ec0: 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a  n 3.3.8 [dateof:
4ed0: 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61  3.3.8].** and la
4ee0: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
4ef0: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
4f00: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
4f10: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
4f20: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
4f30: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
4f40: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73  out errors. Thes
4f50: 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  e [extended resu
4f60: 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e  lt codes] are en
4f70: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4f80: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4f90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4fa0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4fb0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4fc0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4fd0: 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c  des()] API.  Or,
4fe0: 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f   the extended co
4ff0: 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f  de for.** the mo
5000: 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20  st recent error 
5010: 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
5020: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
5030: 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
5040: 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  de()]..*/.#defin
5050: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5060: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
5070: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5080: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
50a0: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
50b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
50c0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
50d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
50e0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
50f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5100: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5110: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
5120: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
5130: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
5140: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5150: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
5160: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
5170: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
5180: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5190: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
51a0: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
51b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51d0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
51e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
51f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
5200: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5210: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
5220: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5230: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
5240: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5250: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
5260: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5270: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
5280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5290: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
52a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52b0: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
52c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52d0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
52e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52f0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
5300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5310: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
5320: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5330: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
5340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5350: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
5360: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5370: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
53a0: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
53c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53d0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
53e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53f0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
5400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5410: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
5420: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5430: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5450: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
5460: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5470: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
5480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5490: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
54a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54b0: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
54c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54d0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
54e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54f0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5510: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
5520: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5530: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
5540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5550: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
5560: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5570: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
5580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5590: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
55a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55b0: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
55c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55d0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45  IOERR_DELETE_NOE
55e0: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  NT      (SQLITE_
55f0: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29  IOERR | (23<<8))
5600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5610: 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20  IOERR_MMAP      
5620: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5630: 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29  IOERR | (24<<8))
5640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5650: 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54  IOERR_GETTEMPPAT
5660: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5670: 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29  IOERR | (25<<8))
5680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5690: 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20  IOERR_CONVPATH  
56a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56b0: 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29  IOERR | (26<<8))
56c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56d0: 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20  IOERR_VNODE     
56e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56f0: 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29  IOERR | (27<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 20  IOERR_AUTH      
5720: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5730: 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29  IOERR | (28<<8))
5740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5750: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
5760: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
5770: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
5780: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5790: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
57a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
57b0: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
57c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57d0: 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20  E_BUSY_SNAPSHOT 
57e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57f0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c  E_BUSY   |  (2<<
5800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5810: 54 45 5f 4b 56 5f 42 45 46 4f 52 45 20 20 20 20  TE_KV_BEFORE    
5820: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5830: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 7c 20 28 31  TE_NOTFOUND | (1
5840: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5850: 4c 49 54 45 5f 4b 56 5f 41 46 54 45 52 20 20 20  LITE_KV_AFTER   
5860: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5870: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 7c 20  LITE_NOTFOUND | 
5880: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5890: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
58a0: 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28  NOTEMPDIR      (
58b0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
58c0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
58d0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
58e0: 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20  N_ISDIR         
58f0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5900: 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  N | (2<<8)).#def
5910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5920: 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20  PEN_FULLPATH    
5930: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5940: 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  PEN | (3<<8)).#d
5950: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5960: 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20  TOPEN_CONVPATH  
5970: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5980: 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a  TOPEN | (4<<8)).
5990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
59a0: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
59b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
59c0: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
59d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59e0: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
59f0: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
5a00: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
5a10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a20: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
5a30: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
5a40: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
5a50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a60: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
5a70: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
5a80: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5a90: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5aa0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44  QLITE_READONLY_D
5ab0: 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53  BMOVED        (S
5ac0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5ad0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5ae0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5af0: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5b00: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5b10: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5b20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b30: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5b40: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b50: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5b70: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5b80: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b90: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5ba0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5bb0: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5bc0: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5bd0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5be0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bf0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5c00: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5c10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c20: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5c30: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c40: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5c50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c60: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5c70: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c80: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5c90: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ca0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5cc0: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5cd0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5ce0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5cf0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d00: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5d10: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5d20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5d30: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5d40: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d50: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5d60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d70: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5d90: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20  RAINT_ROWID     
5da0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5db0: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a  RAINT |(10<<8)).
5dc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5dd0: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41  OTICE_RECOVER_WA
5de0: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e  L      (SQLITE_N
5df0: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a  OTICE | (1<<8)).
5e00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5e10: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f  OTICE_RECOVER_RO
5e20: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e  LLBACK (SQLITE_N
5e30: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a  OTICE | (2<<8)).
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
5e50: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58  ARNING_AUTOINDEX
5e60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57         (SQLITE_W
5e70: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29  ARNING | (1<<8))
5e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e90: 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20  AUTH_USER       
5ea0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5eb0: 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AUTH | (1<<8)).#
5ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
5ed0: 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c  _LOAD_PERMANENTL
5ee0: 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b  Y     (SQLITE_OK
5ef0: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5f00: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5f10: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5f20: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5f30: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5f40: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5f50: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5f60: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5f70: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5f80: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5f90: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5fa0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5fb0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5fc0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5fd0: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5fe0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5ff0: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
6000: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
6010: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6020: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6030: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
6040: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
6050: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
6060: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6070: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6080: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
6090: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
60a0: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
60b0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
60c0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
60d0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
60e0: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
60f0: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
6100: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6110: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
6120: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
6130: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
6140: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6150: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
6160: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
6170: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
6180: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6190: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
61a0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
61b0: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
61c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
61d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
61e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
61f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6200: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
6210: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6220: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6230: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
6240: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
6250: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
6260: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6270: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
6280: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
6290: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
62a0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
62c0: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
62d0: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
62e0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62f0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
6300: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6310: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
6320: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6330: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
6340: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6350: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
6360: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6370: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
6380: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
6390: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
63a0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
63b0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
63c0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
63d0: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
63e0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
63f0: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
6400: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
6410: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
6420: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6430: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6440: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
6450: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
6460: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
6470: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6480: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6490: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
64a0: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
64b0: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
64c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
64d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
64e0: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
64f0: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
6500: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
6510: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6520: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6530: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
6540: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6550: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
6560: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
6570: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
6580: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6590: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
65a0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
65b0: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
65c0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
65d0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
65e0: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
65f0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6600: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
6610: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
6620: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
6630: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6640: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
6650: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
6660: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
6670: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
6680: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
6690: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
66a0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
66b0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
66c0: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
66d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66e0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
66f0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6700: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6710: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6720: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6730: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6740: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
6750: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
6760: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6770: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6780: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
6790: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
67a0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
67b0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
67c0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
67d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
67e0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
67f0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6800: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6810: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6820: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6830: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6840: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
6850: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
6860: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6870: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6880: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
6890: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
68a0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
68b0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
68c0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
68d0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
68e0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
68f0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6900: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
6910: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6920: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
6930: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6940: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
6950: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
6960: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
6970: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
6980: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
6990: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
69a0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
69b0: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
69c0: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
69d0: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
69e0: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
69f0: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6a00: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
6a10: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
6a20: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
6a30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6a40: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6a50: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
6a60: 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65  cate that a file
6a70: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
6a80: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
6a90: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
6aa0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
6ab0: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
6ac0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
6ad0: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
6ae0: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
6af0: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
6b00: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
6b10: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
6b20: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  ileges..*/.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b40: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6b50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6b60: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6b90: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6bb0: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6bc0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6be0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6bf0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c00: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6c10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6c20: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6c30: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6c40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c50: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6c60: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6c70: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6c80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6c90: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6ca0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6cb0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6cc0: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6cd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6ce0: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6cf0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6d00: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6d10: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6d20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6d30: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6d40: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6d80: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6d90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6da0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6db0: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
6dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6dd0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6de0: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
6df0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
6e00: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6e10: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
6e20: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a    0x00002000../*
6e30: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6e40: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6e50: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6e60: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6e70: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6e80: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6e90: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6ea0: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6eb0: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6ec0: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6ed0: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6ee0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6ef0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6f00: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6f10: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6f20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f30: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6f40: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6f50: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6f60: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6f70: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6f80: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6f90: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6fa0: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6fb0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6fc0: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6fd0: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6fe0: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6ff0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
7000: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
7010: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7020: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
7030: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
7040: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
7050: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
7060: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
7070: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
7080: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7090: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
70a0: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
70b0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
70c0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
70d0: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
70e0: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
70f0: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
7100: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
7110: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
7120: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
7130: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
7140: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
7150: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
7160: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
7170: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7180: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
7190: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
71a0: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
71b0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
71c0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
71d0: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
71e0: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
71f0: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
7200: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
7210: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
7220: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7230: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7240: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
7250: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
7260: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
7270: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
7280: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
7290: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
72a0: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
72b0: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
72c0: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
72d0: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
72e0: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
72f0: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
7300: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
7310: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
7320: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7330: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7340: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
7350: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
7360: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
7370: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
7380: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
7390: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
73a0: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
73b0: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
73c0: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
73d0: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
73e0: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
73f0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7400: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
7410: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
7420: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
7430: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7440: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7450: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
7460: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
7470: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
7480: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
7490: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
74a0: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
74b0: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
74c0: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
74d0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
74e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
74f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7500: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
7510: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
7520: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7530: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
7540: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
7550: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7560: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
7570: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
7580: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7590: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
75a0: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
75b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
75c0: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
75d0: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
75e0: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
75f0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7600: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
7610: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
7620: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
7630: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
7640: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
7650: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
7660: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
7670: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
7680: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7690: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
76a0: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
76b0: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
76c0: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
76d0: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
76e0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
76f0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7700: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
7710: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
7720: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
7730: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
7740: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7750: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
7760: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
7770: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
7780: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7790: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
77a0: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
77b0: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
77c0: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
77d0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
77e0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
77f0: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
7800: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7810: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
7820: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
7830: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
7840: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7850: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
7860: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
7870: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
7880: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7890: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
78a0: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
78b0: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
78c0: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
78d0: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
78e0: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
78f0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7900: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
7910: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
7920: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7930: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
7940: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7950: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
7960: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
7970: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
7980: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7990: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
79a0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
79b0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
79c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
79d0: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
79e0: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
79f0: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
7a00: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
7a10: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
7a20: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
7a30: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7a40: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
7a50: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7a60: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7a70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7a80: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7a90: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7aa0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7ab0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7ac0: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7ad0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7ae0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7af0: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7b00: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
7b10: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7b20: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
7b30: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
7b40: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7b50: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
7b60: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7b70: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7b80: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7b90: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7ba0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7bb0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7bc0: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7bd0: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7be0: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7bf0: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7c00: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
7c10: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7c20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7c30: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
7c40: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7c50: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
7c60: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7c70: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7c80: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7c90: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7ca0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7cb0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7cc0: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7cd0: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7ce0: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7cf0: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7d00: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7d10: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7d20: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
7d30: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7d50: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7d60: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7d70: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7d80: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7d90: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7da0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7db0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7dc0: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7dd0: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7de0: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7df0: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7e00: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7e10: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7e20: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7e30: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7e40: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7e50: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7e60: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7e70: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7e80: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7e90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7ea0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7eb0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7ec0: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7ed0: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7ee0: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7ef0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7f00: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7f10: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7f20: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7f30: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7f40: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7f50: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7f60: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7f70: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7f80: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7f90: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7fa0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7fb0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7fc0: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7fd0: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7fe0: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7ff0: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
8000: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
8010: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
8020: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
8030: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
8040: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
8050: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
8060: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
8070: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
8080: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
8090: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
80a0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
80b0: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e  ..** A [file con
80c0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c  trol opcodes | l
80d0: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
80e0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
80f0: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
8100: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
8110: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
8120: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8130: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
8140: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
8150: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
8160: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
8170: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
8180: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
8190: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
81a0: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
81b0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
81c0: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
81d0: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
81e0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
81f0: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
8200: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
8210: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
8220: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
8230: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
8240: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
8250: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
8260: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
8270: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
8280: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
8290: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
82a0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
82b0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
82c0: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
82d0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
82e0: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
82f0: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
8300: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
8310: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
8320: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8330: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8340: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
8350: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8360: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
8370: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8380: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
8390: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83a0: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
83b0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83c0: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
83d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83e0: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
83f0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8400: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
8410: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8420: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
8430: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8440: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8450: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8460: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
8470: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8480: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
8490: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
84a0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
84b0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
84c0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
84d0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
84e0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
84f0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8500: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
8510: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
8520: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
8530: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
8540: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
8550: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
8560: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8570: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
8580: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
8590: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
85a0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
85b0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
85c0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
85d0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
85e0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
85f0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
8600: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
8610: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
8620: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
8630: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
8640: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
8650: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8660: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8670: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8680: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8690: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
86a0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
86b0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
86c0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
86d0: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
86e0: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
86f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
8700: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
8710: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
8720: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
8730: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
8740: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
8750: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8760: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8770: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8780: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8790: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
87a0: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
87b0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
87c0: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
87d0: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
87e0: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
87f0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8800: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8810: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
8820: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
8830: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8840: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8850: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8860: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8870: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8880: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8890: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
88a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
88b0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
88c0: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
88d0: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
88e0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
88f0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8900: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
8910: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
8920: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8930: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
8940: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
8950: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8960: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8970: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8980: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8990: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
89a0: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
89b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
89c0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
89d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89e0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
89f0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
8a00: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8a10: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
8a20: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
8a30: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
8a40: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
8a50: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
8a60: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8a70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8a80: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
8a90: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
8aa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8ab0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8ac0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8ad0: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
8ae0: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
8af0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8b00: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
8b10: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
8b20: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
8b30: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
8b40: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
8b50: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
8b60: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8b70: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8b80: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8b90: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
8ba0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8bb0: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
8bc0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8bd0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8be0: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
8bf0: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
8c00: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8c10: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8c20: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
8c30: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
8c40: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
8c50: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8c60: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
8c70: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8c80: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8c90: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8ca0: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
8cb0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
8cc0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
8cd0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
8ce0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
8cf0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
8d00: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
8d10: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
8d20: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8d30: 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f  pcodes} {file co
8d40: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a  ntrol opcode}.**
8d50: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8d60: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
8d70: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
8d80: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8d90: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
8da0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8db0: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
8dc0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
8dd0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
8de0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
8df0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8e00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
8e10: 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65  CKSTATE]].** The
8e20: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8e30: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8e40: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8e50: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8e60: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8e70: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8e80: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8e90: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8ea0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8eb0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
8ec0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
8ed0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
8ee0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
8ef0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
8f00: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8f10: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8f20: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8f30: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8f40: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8f50: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8f60: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8f70: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
8f80: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
8f90: 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  and is only avai
8fa0: 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53  lable when the S
8fb0: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f  QLITE_TEST.** co
8fc0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
8fd0: 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
8fe0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8ff0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
9000: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9010: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
9020: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
9030: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
9040: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
9050: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
9060: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
9070: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
9080: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
9090: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
90a0: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
90b0: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
90c0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
90d0: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
90e0: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
90f0: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
9100: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
9110: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
9120: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
9130: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
9140: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
9150: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
9160: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
9170: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
9180: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
9190: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
91a0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
91b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
91c0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
91d0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
91e0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
91f0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
9200: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
9210: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9220: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
9230: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
9240: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
9250: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
9260: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
9270: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
9280: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
9290: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
92a0: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
92b0: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
92c0: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
92d0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
92e0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
92f0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
9300: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
9310: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
9320: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
9330: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
9340: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
9350: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
9360: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
9370: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
9380: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
9390: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
93a0: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
93b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
93c0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
93d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
93e0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
93f0: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9400: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9410: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9420: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
9430: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
9440: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f  ction.  See also
9450: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
9460: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e  OURNAL_POINTER].
9470: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9480: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9490: 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  L_POINTER]].** T
94a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
94b0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
94c0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
94d0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
94e0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
94f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9500: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
9510: 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c  with the journal
9520: 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a   file (either.**
9530: 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a   the [rollback j
9540: 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b  ournal] or the [
9550: 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d  write-ahead log]
9560: 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ) for a particul
9570: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9580: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9590: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
95a0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
95b0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
95c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
95d0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
95e0: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
95f0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9600: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9610: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9620: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9630: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9640: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9650: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
9660: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
9670: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
9680: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
9690: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
96a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
96b0: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
96c0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
96d0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
96e0: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
96f0: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9700: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9710: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9720: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9730: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
9740: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
9750: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
9760: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9770: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
9780: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
9790: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
97a0: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
97b0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
97c0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
97d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
97e0: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
97f0: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
9800: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
9810: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
9820: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
9830: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
9840: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
9850: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
9860: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
9870: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
9880: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
9890: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
98a0: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
98b0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
98c0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
98d0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
98e0: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
98f0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9900: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9910: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9920: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
9930: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
9940: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9950: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9960: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9970: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9980: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9990: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
99a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
99b0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
99c0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
99d0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
99e0: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
99f0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
9a00: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
9a10: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
9a20: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
9a30: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
9a40: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
9a50: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
9a60: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
9a70: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
9a80: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9a90: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9aa0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
9ab0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9ac0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9ad0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9ae0: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9af0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
9b00: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
9b10: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9b20: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9b30: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9b40: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9b50: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9b60: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
9b70: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9b80: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9b90: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
9ba0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
9bb0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
9bc0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
9bd0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
9be0: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9bf0: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9c00: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9c10: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9c20: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9c30: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
9c40: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
9c50: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
9c60: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
9c70: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
9c80: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
9c90: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
9ca0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
9cb0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
9cc0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
9cd0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
9ce0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9cf0: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9d00: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9d10: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9d20: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9d30: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
9d40: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
9d50: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
9d60: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
9d70: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
9d80: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
9d90: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
9da0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
9db0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
9dc0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
9dd0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
9de0: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9df0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9e00: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9e10: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9e20: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9e30: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
9e40: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
9e50: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
9e60: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
9e70: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
9e80: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
9e90: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
9ea0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
9eb0: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
9ec0: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
9ed0: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
9ee0: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9ef0: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9f00: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9f10: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9f20: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
9f30: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
9f40: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
9f50: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
9f60: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
9f70: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
9f80: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
9f90: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
9fa0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9fb0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
9fc0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9fd0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9fe0: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9ff0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
a000: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
a010: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
a020: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
a030: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
a040: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
a050: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
a060: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
a070: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
a080: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
a090: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
a0a0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
a0b0: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
a0c0: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
a0d0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
a0e0: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
a0f0: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
a100: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
a110: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
a120: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
a130: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
a140: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
a150: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
a160: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
a170: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
a180: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
a190: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
a1a0: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
a1b0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
a1c0: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
a1d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a1e0: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
a1f0: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
a200: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
a210: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
a220: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
a230: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
a240: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a250: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a260: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a270: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a280: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a290: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a2a0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a2b0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a2c0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
a2d0: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
a2e0: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
a2f0: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
a300: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
a310: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
a320: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
a330: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
a340: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
a350: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
a360: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a370: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
a380: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
a390: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a3a0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a3b0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
a3c0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
a3d0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
a3e0: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
a3f0: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
a400: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
a410: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
a420: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
a430: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
a440: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a450: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
a460: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
a470: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
a480: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
a490: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a4a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a4b0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a4c0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a4d0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a4e0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a4f0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a500: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
a510: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
a520: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
a530: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
a540: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
a550: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
a560: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
a570: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
a580: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
a590: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
a5a0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a5b0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
a5c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a5d0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a5e0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
a5f0: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
a600: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
a610: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
a620: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
a630: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
a640: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
a650: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
a660: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
a670: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
a680: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
a690: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
a6a0: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
a6b0: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
a6c0: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
a6d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a6e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a6f0: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
a700: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a710: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
a720: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
a730: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
a740: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
a750: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
a760: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
a770: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
a780: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
a790: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
a7a0: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
a7b0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a7c0: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
a7d0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
a7e0: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
a7f0: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
a800: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
a810: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
a820: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
a830: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a840: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
a850: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
a860: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
a870: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
a880: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
a890: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
a8a0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
a8b0: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
a8c0: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
a8d0: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
a8e0: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
a8f0: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
a900: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
a910: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a920: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
a930: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
a940: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a950: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
a960: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
a970: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
a980: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
a990: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
a9a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a9b0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
a9c0: 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NTER]].** ^The [
a9d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a9e0: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
a9f0: 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72   finds a pointer
aa00: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
aa10: 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72  l.** [VFSes] cur
aa20: 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20  rently in use.  
aa30: 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58  ^(The argument X
aa40: 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66   in.** sqlite3_f
aa50: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53  ile_control(db,S
aa60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
aa70: 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20  POINTER,X) must 
aa80: 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b  be.** of type "[
aa90: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22  sqlite3_vfs] **"
aaa0: 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20  .  This opcodes 
aab0: 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74  will set *X.** t
aac0: 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  o a pointer to t
aad0: 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53  he top-level VFS
aae0: 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  .)^.** ^When the
aaf0: 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20  re are multiple 
ab00: 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65  VFS shims in the
ab10: 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63   stack, this opc
ab20: 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a  ode finds the.**
ab30: 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d   upper-most shim
ab40: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
ab50: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ab60: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
ab70: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
ab80: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
ab90: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
aba0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
abb0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
abc0: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
abd0: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
abe0: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
abf0: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
ac00: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
ac10: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
ac20: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
ac30: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
ac40: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
ac50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ac60: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
ac70: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
ac80: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
ac90: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
aca0: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
acb0: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
acc0: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
acd0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
ace0: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
acf0: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
ad00: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
ad10: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
ad20: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
ad30: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
ad40: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
ad50: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
ad60: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ad70: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
ad80: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
ad90: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
ada0: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
adb0: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
adc0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
add0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
ade0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
adf0: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
ae00: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
ae10: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
ae20: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
ae30: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
ae40: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
ae50: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
ae60: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
ae70: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
ae80: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
ae90: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
aea0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
aeb0: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
aec0: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
aed0: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
aee0: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
aef0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
af00: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
af10: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
af20: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
af30: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
af40: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
af50: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
af60: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
af70: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
af80: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
af90: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
afa0: 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72  nt if result str
afb0: 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20  ing is NULL, or 
afc0: 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63  that returns a c
afd0: 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  opy.** of the re
afe0: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74  sult string if t
aff0: 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e  he string is non
b000: 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68  -NULL..** ^If th
b010: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b020: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
b030: 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20  trol returns.** 
b040: 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  any result code 
b050: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
b060: 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54  TE_OK] or [SQLIT
b070: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61  E_NOTFOUND], tha
b080: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  t means.** that 
b090: 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65  the VFS encounte
b0a0: 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69  red an error whi
b0b0: 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20  le handling the 
b0c0: 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65  [PRAGMA] and the
b0d0: 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  .** compilation 
b0e0: 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61  of the PRAGMA fa
b0f0: 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ils with an erro
b100: 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  r.  ^The [SQLITE
b110: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
b120: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  * file control o
b130: 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67  ccurs at the beg
b140: 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61  inning of pragma
b150: 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79   statement analy
b160: 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74  sis and so.** it
b170: 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72   is able to over
b180: 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50  ride built-in [P
b190: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
b1a0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
b1b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
b1c0: 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68  HANDLER]].** ^Th
b1d0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b1e0: 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20  BUSYHANDLER].** 
b1f0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79  file-control may
b200: 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   be invoked by S
b210: 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74  QLite on the dat
b220: 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c  abase file handl
b230: 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74  e.** shortly aft
b240: 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20  er it is opened 
b250: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
b260: 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53  ide a custom VFS
b270: 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20   with access.** 
b280: 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  to the connectio
b290: 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  ns busy-handler 
b2a0: 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72  callback. The ar
b2b0: 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70  gument is of typ
b2c0: 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d  e (void **).** -
b2d0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
b2e0: 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73   (void *) values
b2f0: 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69  . The first (voi
b300: 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f  d *) actually po
b310: 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e  ints.** to a fun
b320: 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69  ction of type (i
b330: 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e  nt (*)(void *)).
b340: 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76   In order to inv
b350: 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  oke the connecti
b360: 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64  ons.** busy-hand
b370: 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ler, this functi
b380: 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76  on should be inv
b390: 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65  oked with the se
b3a0: 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e  cond (void *) in
b3b0: 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73  .** the array as
b3c0: 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65   the only argume
b3d0: 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  nt. If it return
b3e0: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
b3f0: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
b400: 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72  * should be retr
b410: 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72  ied. If it retur
b420: 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73  ns zero, the cus
b430: 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61  tom VFS should a
b440: 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75  bandon the.** cu
b450: 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e  rrent operation.
b460: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b470: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
b480: 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70  LENAME]].** ^App
b490: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76  lication can inv
b4a0: 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  oke the [SQLITE_
b4b0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
b4c0: 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  ME] file-control
b4d0: 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69  .** to have SQLi
b4e0: 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a  te generate a.**
b4f0: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
b500: 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ame using the sa
b510: 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61  me algorithm tha
b520: 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f  t is followed to
b530: 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d   generate.** tem
b540: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73  porary filenames
b550: 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73   for TEMP tables
b560: 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72   and other inter
b570: 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a  nal uses.  The.*
b580: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
b590: 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68  d be a char** wh
b5a0: 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c  ich will be fill
b5b0: 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65  ed with the file
b5c0: 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20  name.** written 
b5d0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
b5e0: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
b5f0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
b600: 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64  he caller should
b610: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  .** invoke [sqli
b620: 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74  te3_free()] on t
b630: 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f  he result to avo
b640: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  id a memory leak
b650: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b660: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
b670: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
b680: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b690: 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
b6a0: 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71  rol is used to q
b6b0: 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a  uery or set the.
b6c0: 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ** maximum numbe
b6d0: 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20  r of bytes that 
b6e0: 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72  will be used for
b6f0: 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49   memory-mapped I
b700: 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  /O..** The argum
b710: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
b720: 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74   to a value of t
b730: 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ype sqlite3_int6
b740: 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20  4 that.** is an 
b750: 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d  advisory maximum
b760: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b770: 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20   in the file to 
b780: 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65  memory map.  The
b790: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f  .** pointer is o
b7a0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
b7b0: 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20  the old value.  
b7c0: 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  The limit is not
b7d0: 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74   changed if.** t
b7e0: 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61  he value origina
b7f0: 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69  lly pointed to i
b800: 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20  s negative, and 
b810: 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c  so the current l
b820: 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20  imit .** can be 
b830: 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69  queried by passi
b840: 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20  ng in a pointer 
b850: 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  to a negative nu
b860: 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66  mber.  This.** f
b870: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile-control is u
b880: 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
b890: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41  o implement [PRA
b8a0: 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a  GMA mmap_size]..
b8b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b8c0: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d  TE_FCNTL_TRACE]]
b8d0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b8e0: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c  FCNTL_TRACE] fil
b8f0: 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64  e control provid
b900: 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f  es advisory info
b910: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68  rmation.** to th
b920: 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74  e VFS about what
b930: 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65   the higher laye
b940: 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  rs of the SQLite
b950: 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67   stack are doing
b960: 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63  ..** This file c
b970: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62  ontrol is used b
b980: 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76  y some VFS activ
b990: 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69  ity tracing [shi
b9a0: 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ms]..** The argu
b9b0: 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74  ment is a zero-t
b9c0: 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
b9d0: 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73  .  Higher layers
b9e0: 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74   in the.** SQLit
b9f0: 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65  e stack may gene
ba00: 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f  rate instances o
ba10: 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  f this file cont
ba20: 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53  rol if.** the [S
ba30: 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f  QLITE_USE_FCNTL_
ba40: 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  TRACE] compile-t
ba50: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
ba60: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  abled..**.** <li
ba70: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ba80: 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54  HAS_MOVED]].** T
ba90: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
baa0: 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65  _HAS_MOVED] file
bab0: 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72   control interpr
bac0: 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74  ets its argument
bad0: 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   as a.** pointer
bae0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61   to an integer a
baf0: 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62  nd it writes a b
bb00: 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74  oolean into that
bb10: 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69   integer dependi
bb20: 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  ng.** on whether
bb30: 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65   or not the file
bb40: 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65   has been rename
bb50: 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c  d, moved, or del
bb60: 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a  eted since it.**
bb70: 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65   was first opene
bb80: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
bb90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
bba0: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a  2_GET_HANDLE]].*
bbb0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bbc0: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
bbd0: 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NDLE] opcode can
bbe0: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
bbf0: 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  in the.** underl
bc00: 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65  ying native file
bc10: 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74   handle associat
bc20: 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20 68  ed with a file h
bc30: 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c  andle.  This fil
bc40: 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  e.** control int
bc50: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
bc60: 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65  ment as a pointe
bc70: 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69  r to a native fi
bc80: 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a  le handle and.**
bc90: 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75   writes the resu
bca0: 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72  lting value ther
bcb0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
bcc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
bcd0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a  2_SET_HANDLE]].*
bce0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bcf0: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
bd00: 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  NDLE] opcode is 
bd10: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
bd20: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
bd30: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
bd40: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
bd50: 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66  od to swap the f
bd60: 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20  ile handle with 
bd70: 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74  the one.** point
bd80: 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72  ed to by the pAr
bd90: 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69  g argument.  Thi
bda0: 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20  s capability is 
bdb0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
bdc0: 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20  ing.** and only 
bdd0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
bde0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
bdf0: 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65  E_TEST is define
be00: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
be10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
be20: 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b  BLOCK]].** The [
be30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
be40: 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67  _BLOCK] is a sig
be50: 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c  nal to the VFS l
be60: 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67  ayer that it mig
be70: 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61  ht.** be advanta
be80: 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f  geous to block o
be90: 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c  n the next WAL l
bea0: 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20  ock if the lock 
beb0: 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65  is not immediate
bec0: 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e  ly.** available.
bed0: 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73    The WAL subsys
bee0: 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20  tem issues this 
bef0: 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61  signal during ra
bf00: 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e  re.** circumstan
bf10: 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ces in order to 
bf20: 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69  fix a problem wi
bf30: 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65  th priority inve
bf40: 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63  rsion..** Applic
bf50: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65  ations should <e
bf60: 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74  m>not</em> use t
bf70: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
bf80: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
bf90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
bfa0: 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  S]].** The [SQLI
bfb0: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
bfc0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
bfd0: 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73  mented by zipvfs
bfe0: 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72   only. All other
bff0: 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72  .** VFS should r
c000: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54  eturn SQLITE_NOT
c010: 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f  FOUND for this o
c020: 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pcode..**.** <li
c030: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c040: 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  RBU]].** The [SQ
c050: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20  LITE_FCNTL_RBU] 
c060: 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d  opcode is implem
c070: 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70 65  ented by the spe
c080: 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62 79  cial VFS used by
c090: 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74 65  .** the RBU exte
c0a0: 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c  nsion only.  All
c0b0: 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c   other VFS shoul
c0c0: 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  d return SQLITE_
c0d0: 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20  NOTFOUND for.** 
c0e0: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a  this opcode.  .*
c0f0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
c100: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c110: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
c120: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
c130: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47  e SQLITE_FCNTL_G
c140: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c150: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
c160: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
c170: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c180: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
c190: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
c1a0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
c1b0: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
c1c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
c1d0: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
c1e0: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
c1f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
c200: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
c210: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
c220: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
c230: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
c240: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
c250: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
c260: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
c270: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
c280: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
c290: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
c2a0: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
c2b0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
c2c0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
c2d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c2e0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
c2f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
c300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c310: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
c320: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
c330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c340: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
c350: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
c360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c370: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
c380: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
c390: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c3a0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
c3b0: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
c3c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c3d0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
c3e0: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
c3f0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c400: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
c410: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
c420: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
c430: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
c440: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
c450: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
c460: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
c470: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
c480: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
c490: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
c4a0: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
c4b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c4c0: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
c4d0: 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51     22.#define SQ
c4e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c4f0: 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _SET_HANDLE     
c500: 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    23.#define SQL
c510: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
c520: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
c530: 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   24.#define SQLI
c540: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20  TE_FCNTL_ZIPVFS 
c550: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c560: 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  25.#define SQLIT
c570: 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20  E_FCNTL_RBU     
c580: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
c590: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
c5a0: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
c5b0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37  ER            27
c5c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c5d0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
c5e0: 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a  INTER        28.
c5f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c600: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c610: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23  ANDLE       29.#
c620: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c630: 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20  NTL_PDB         
c640: 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 0a 2f             30../
c650: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d  * deprecated nam
c660: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
c670: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
c680: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c690: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
c6a0: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c6b0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
c6c0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c6d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
c6e0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
c6f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
c700: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
c710: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c720: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a  TL_LAST_ERRNO...
c730: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c740: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
c750: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
c760: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
c770: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
c780: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
c790: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
c7a0: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
c7b0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
c7c0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
c7d0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
c7e0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
c7f0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
c800: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
c810: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
c820: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
c830: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
c840: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
c850: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
c860: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
c870: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
c880: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
c890: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c8a0: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
c8b0: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
c8c0: 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45  3REF: Loadable E
c8d0: 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a  xtension Thunk.*
c8e0: 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
c8f0: 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c  o the opaque sql
c900: 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65  ite3_api_routine
c910: 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 70  s structure is p
c920: 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20  assed as.** the 
c930: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
c940: 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20  to entry points 
c950: 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74  of [loadable ext
c960: 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a  ensions].  This.
c970: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  ** structure mus
c980: 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20 69  t be typedefed i
c990: 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20  n order to work 
c9a0: 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20  around compiler 
c9b0: 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73  warnings.** on s
c9c0: 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  ome platforms..*
c9d0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
c9e0: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
c9f0: 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70  tines sqlite3_ap
ca00: 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a  i_routines;../*.
ca10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
ca20: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
ca30: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
ca40: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
ca50: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
ca60: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
ca70: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
ca80: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
ca90: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
caa0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
cab0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
cac0: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
cad0: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
cae0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
caf0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
cb00: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
cb10: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
cb20: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
cb30: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
cb40: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
cb50: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
cb60: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
cb70: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
cb80: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
cb90: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
cba0: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
cbb0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
cbc0: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
cbd0: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
cbe0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
cbf0: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
cc00: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
cc10: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
cc20: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
cc30: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
cc40: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
cc50: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
cc60: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
cc70: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
cc80: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
cc90: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
cca0: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
ccb0: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
ccc0: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
ccd0: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
cce0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
ccf0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
cd00: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
cd10: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
cd20: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
cd30: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
cd40: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
cd50: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
cd60: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
cd70: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
cd80: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
cd90: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
cda0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
cdb0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
cdc0: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
cdd0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
cde0: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
cdf0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
ce00: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
ce10: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
ce20: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
ce30: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
ce40: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
ce50: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
ce60: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
ce70: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
ce80: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
ce90: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
cea0: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
ceb0: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
cec0: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
ced0: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
cee0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
cef0: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
cf00: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
cf10: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
cf20: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
cf30: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
cf40: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
cf50: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
cf60: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
cf70: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
cf80: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
cf90: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
cfa0: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
cfb0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
cfc0: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
cfd0: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
cfe0: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
cff0: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
d000: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
d010: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
d020: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
d030: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
d040: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
d050: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
d060: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
d070: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
d080: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
d090: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
d0a0: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
d0b0: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
d0c0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
d0d0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
d0e0: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
d0f0: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
d100: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
d110: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
d120: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
d130: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
d140: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
d150: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
d160: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
d170: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
d180: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
d190: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
d1a0: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
d1b0: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
d1c0: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
d1d0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
d1e0: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
d1f0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
d200: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
d210: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
d220: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
d230: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
d240: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
d250: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
d260: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
d270: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
d280: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
d290: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
d2a0: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
d2b0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
d2c0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
d2d0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
d2e0: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
d2f0: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
d300: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
d310: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
d320: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
d330: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
d340: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
d350: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d360: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
d370: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
d380: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
d390: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
d3a0: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
d3b0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d3c0: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
d3d0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d3e0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
d3f0: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
d400: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
d410: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
d420: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
d430: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
d440: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
d450: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
d460: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
d470: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
d480: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
d490: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
d4a0: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
d4b0: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
d4c0: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
d4d0: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
d4e0: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
d4f0: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
d500: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
d510: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
d520: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
d530: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
d540: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
d550: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
d560: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
d570: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
d580: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
d590: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
d5a0: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
d5b0: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
d5c0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
d5d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d5e0: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
d5f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
d600: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
d610: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d620: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
d630: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d640: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
d650: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d660: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
d670: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d680: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
d690: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d6a0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
d6b0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
d6c0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d6d0: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
d6e0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
d6f0: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
d700: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
d710: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
d720: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
d730: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
d740: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
d750: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
d760: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
d770: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
d780: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
d790: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
d7a0: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
d7b0: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
d7c0: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
d7d0: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
d7e0: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
d7f0: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
d800: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
d810: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
d820: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
d830: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
d840: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
d850: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
d860: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
d870: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
d880: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
d890: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
d8a0: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
d8b0: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
d8c0: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
d8d0: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
d8e0: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
d8f0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
d900: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
d910: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
d920: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
d930: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
d940: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
d950: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
d960: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
d970: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
d980: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
d990: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
d9a0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d9b0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
d9c0: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
d9d0: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
d9e0: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
d9f0: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
da00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
da10: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
da20: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
da30: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
da40: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
da50: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
da60: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
da70: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
da80: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
da90: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
daa0: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
dab0: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
dac0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
dad0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
dae0: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
daf0: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
db00: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
db10: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
db20: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
db30: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
db40: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
db50: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
db60: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
db70: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
db80: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
db90: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
dba0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
dbb0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
dbc0: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
dbd0: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
dbe0: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
dbf0: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
dc00: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
dc10: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
dc20: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
dc30: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
dc40: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
dc50: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
dc60: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
dc70: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
dc80: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
dc90: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
dca0: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
dcb0: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
dcc0: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
dcd0: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
dce0: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
dcf0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
dd00: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
dd10: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
dd20: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
dd30: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
dd40: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
dd50: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
dd60: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
dd70: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
dd80: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
dd90: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
dda0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
ddb0: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
ddc0: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
ddd0: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
dde0: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
ddf0: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
de00: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
de10: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
de20: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
de30: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
de40: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
de50: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
de60: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
de70: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
de80: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
de90: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
dea0: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
deb0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
dec0: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
ded0: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
dee0: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
def0: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
df00: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
df10: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
df20: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
df30: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
df40: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
df50: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
df60: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
df70: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
df80: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
df90: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
dfa0: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
dfb0: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
dfc0: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
dfd0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
dfe0: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
dff0: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
e000: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
e010: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
e020: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
e030: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
e040: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
e050: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
e060: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
e070: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
e080: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
e090: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
e0a0: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
e0b0: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
e0c0: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
e0d0: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
e0e0: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
e0f0: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
e100: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
e110: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
e120: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
e130: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
e140: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
e150: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
e160: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
e170: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
e180: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
e190: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
e1a0: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
e1b0: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
e1c0: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
e1d0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
e1e0: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
e1f0: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
e200: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
e210: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
e220: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
e230: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
e240: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
e250: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
e260: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
e270: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
e280: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
e290: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
e2a0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
e2b0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
e2c0: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
e2d0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
e2e0: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
e2f0: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
e300: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
e310: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
e320: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
e330: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
e340: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
e350: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
e360: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
e370: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
e380: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
e390: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
e3a0: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
e3b0: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
e3c0: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
e3d0: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
e3e0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e3f0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
e400: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
e410: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
e420: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
e430: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
e440: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
e450: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
e460: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
e470: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
e480: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
e490: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e4a0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
e4b0: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
e4c0: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
e4d0: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
e4e0: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
e4f0: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
e500: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
e510: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
e520: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
e530: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
e540: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
e550: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
e560: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
e570: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
e580: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
e590: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
e5a0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
e5b0: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
e5c0: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
e5d0: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
e5e0: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
e5f0: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
e600: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
e610: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
e620: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
e630: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
e640: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
e650: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
e660: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
e670: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
e680: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
e690: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
e6a0: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
e6b0: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
e6c0: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
e6d0: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
e6e0: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
e6f0: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
e700: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
e710: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
e720: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
e730: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
e740: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
e750: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
e760: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
e770: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
e780: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
e790: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
e7a0: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
e7b0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e7c0: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
e7d0: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
e7e0: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
e7f0: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
e800: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
e810: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
e820: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
e830: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
e840: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
e850: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
e860: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
e870: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
e880: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
e890: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
e8a0: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
e8b0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e8c0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
e8d0: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
e8e0: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
e8f0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
e900: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
e910: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
e920: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
e930: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
e940: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
e950: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
e960: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
e970: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
e980: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
e990: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
e9a0: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
e9b0: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
e9c0: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
e9d0: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
e9e0: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
e9f0: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
ea00: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
ea10: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
ea20: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
ea30: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
ea40: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
ea50: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
ea60: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
ea70: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
ea80: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
ea90: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
eaa0: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
eab0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
eac0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
ead0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
eae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
eaf0: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
eb00: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
eb10: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
eb20: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
eb30: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
eb40: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
eb50: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
eb60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
eb70: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
eb80: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
eb90: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
eba0: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
ebb0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ebc0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
ebd0: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
ebe0: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
ebf0: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
ec00: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ec10: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
ec20: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
ec30: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
ec40: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
ec50: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
ec60: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
ec70: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
ec80: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
ec90: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
eca0: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
ecb0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
ecc0: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
ecd0: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
ece0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
ecf0: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
ed00: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
ed10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ed20: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
ed30: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
ed40: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
ed50: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
ed60: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
ed70: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
ed80: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
ed90: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
eda0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
edb0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
edc0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
edd0: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
ede0: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
edf0: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
ee00: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
ee10: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
ee20: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
ee30: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
ee40: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
ee50: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
ee60: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
ee70: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
ee80: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
ee90: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
eea0: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
eeb0: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
eec0: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
eed0: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
eee0: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
eef0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
ef00: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ef10: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
ef20: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
ef30: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
ef40: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
ef50: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
ef60: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ef70: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
ef80: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
ef90: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
efa0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
efb0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
efc0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
efd0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
efe0: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
eff0: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
f000: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
f010: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
f020: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
f030: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  future versions.
f040: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
f050: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
f060: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
f070: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
f080: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
f090: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
f0a0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
f0b0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
f0c0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
f0d0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
f0e0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
f0f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
f100: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
f110: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
f120: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
f130: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
f140: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
f150: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
f160: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
f170: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
f180: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
f190: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
f1a0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f1b0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
f1c0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
f1d0: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
f1e0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
f1f0: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
f200: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
f210: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
f220: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
f230: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
f240: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
f250: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
f260: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
f270: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
f280: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
f290: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
f2a0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
f2b0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
f2c0: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
f2d0: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
f2e0: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
f2f0: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
f300: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
f310: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
f320: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
f330: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
f340: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
f350: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
f360: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
f370: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
f380: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
f390: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
f3a0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
f3b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
f3c0: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
f3d0: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
f3e0: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
f3f0: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
f400: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
f410: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
f420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f430: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
f440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f450: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
f460: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
f470: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
f480: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
f490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f4a0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
f4b0: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
f4c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
f4d0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
f4e0: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
f4f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
f500: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
f510: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
f520: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
f530: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
f540: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
f550: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
f560: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
f570: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
f580: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
f590: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
f5a0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
f5b0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
f5c0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f5d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f5e0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
f5f0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f600: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f610: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
f620: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
f630: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f640: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f650: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
f660: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
f670: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
f680: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f690: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
f6a0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
f6b0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
f6c0: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
f6d0: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
f6e0: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
f6f0: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
f700: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
f710: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f720: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
f730: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
f740: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
f750: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
f760: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
f770: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
f780: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
f790: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
f7a0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
f7b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f7c0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
f7d0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
f7e0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
f7f0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
f800: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f810: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
f820: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
f830: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
f840: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
f850: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
f860: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
f870: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
f880: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f890: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
f8a0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
f8b0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
f8c0: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
f8d0: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
f8e0: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
f8f0: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
f900: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
f910: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
f920: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
f930: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
f940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f950: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
f960: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
f970: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
f980: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
f990: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f9a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f9b0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
f9c0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
f9d0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
f9e0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
f9f0: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
fa00: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
fa10: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
fa20: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
fa30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fa40: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
fa50: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
fa60: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
fa70: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
fa80: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
fa90: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
faa0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
fab0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
fac0: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
fad0: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
fae0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
faf0: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
fb00: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
fb10: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
fb20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fb30: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
fb40: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
fb50: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
fb60: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
fb70: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
fb80: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
fb90: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
fba0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
fbb0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
fbc0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
fbd0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
fbe0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
fbf0: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
fc00: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fc10: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
fc20: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
fc30: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
fc40: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
fc50: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
fc60: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
fc70: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
fc80: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
fc90: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
fca0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
fcb0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
fcc0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
fcd0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
fce0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
fcf0: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
fd00: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
fd10: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
fd20: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
fd30: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
fd40: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
fd50: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
fd60: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
fd70: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
fd80: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
fd90: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
fda0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
fdb0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fdc0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fdd0: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
fde0: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
fdf0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
fe00: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
fe10: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fe20: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
fe30: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
fe40: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
fe50: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
fe60: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
fe70: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
fe80: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
fe90: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
fea0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
feb0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
fec0: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
fed0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
fee0: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
fef0: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
ff00: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
ff10: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
ff20: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
ff30: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
ff40: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
ff50: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
ff60: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
ff70: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
ff80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
ff90: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
ffa0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
ffb0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
ffc0: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
ffd0: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
ffe0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fff0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
10000 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
10010 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
10020 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
10030 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
10040 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
10050 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
10060 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
10070 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
10080 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
10090 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
100a0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
100b0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
100c0 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
100d0 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
100e0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
100f0 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
10100 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
10110 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
10120 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
10130 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10140 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
10150 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
10160 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
10170 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
10180 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
10190 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
101a0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
101b0 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
101c0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
101d0 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
101e0 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
101f0 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
10200 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
10210 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
10220 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10230 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
10240 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
10250 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
10260 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
10270 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
10280 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10290 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
102a0 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
102b0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
102c0 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
102d0 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
102e0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
102f0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
10300 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
10310 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
10320 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
10330 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
10340 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
10350 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
10360 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10370 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
10380 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
10390 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
103a0 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
103b0 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
103c0 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
103d0 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
103e0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
103f0 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
10400 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
10410 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10420 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
10430 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
10440 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
10450 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
10460 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
10470 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
10480 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10490 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
104a0 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
104b0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
104c0 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
104d0 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
104e0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
104f0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10500 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
10510 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
10520 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
10530 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
10540 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
10550 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
10560 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
10570 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
10580 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
10590 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
105a0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
105b0 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
105c0 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
105d0 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
105e0 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
105f0 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
10600 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
10610 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
10620 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10630 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
10640 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
10650 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
10660 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
10670 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
10680 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
10690 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
106a0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
106b0 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
106c0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
106d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
106e0 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
106f0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10700 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
10710 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
10720 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
10730 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
10740 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
10750 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
10760 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
10770 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
10780 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
10790 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
107a0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
107b0 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
107c0 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
107d0 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
107e0 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
107f0 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
10800 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
10810 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
10820 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
10830 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
10840 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
10850 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
10860 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
10870 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
10880 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
10890 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
108a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
108b0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
108c0 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
108d0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
108e0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
108f0 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
10900 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
10910 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
10920 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
10930 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
10940 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
10950 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
10960 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
10970 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
10980 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
10990 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
109a0 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
109b0 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
109c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
109d0 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
109e0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
109f0 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
10a00 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
10a10 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
10a20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
10a30 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10a40 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
10a50 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
10a60 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
10a70 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
10a80 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
10a90 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
10aa0 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
10ab0 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
10ac0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
10ad0 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
10ae0 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
10af0 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
10b00 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
10b10 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
10b20 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
10b30 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
10b40 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
10b50 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
10b60 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
10b70 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
10b80 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71  .**.** <b>The sq
10b90 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10ba0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
10bb0 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 20  threadsafe. The 
10bc0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
10bd0 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20  ust ensure that 
10be0 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
10bf0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
10c00 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
10c10 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
10c20 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10c30 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62  ) is running.</b
10c40 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
10c50 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10c60 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e  erface.** may on
10c70 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
10c80 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
10c90 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
10ca0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
10cb0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
10cc0 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
10cd0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
10ce0 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
10cf0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10d00 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
10d10 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
10d20 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
10d30 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
10d40 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
10d50 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
10d60 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
10d70 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
10d80 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
10d90 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
10da0 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
10db0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
10dc0 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
10dd0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
10de0 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
10df0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
10e00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10e10 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10e20 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
10e30 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
10e40 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
10e50 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
10e60 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
10e70 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
10e80 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
10e90 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
10ea0 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
10eb0 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
10ec0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
10ed0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
10ee0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
10ef0 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
10f00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
10f10 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
10f20 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
10f30 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
10f40 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
10f50 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
10f60 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
10f70 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
10f80 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
10f90 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
10fa0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
10fb0 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
10fc0 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
10fd0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
10fe0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
10ff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11000 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
11010 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
11020 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
11030 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
11040 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
11050 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
11060 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
11070 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11080 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
11090 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
110a0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
110b0 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
110c0 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
110d0 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
110e0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
110f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
11100 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
11110 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
11120 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
11130 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11140 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
11150 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
11160 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
11170 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
11180 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
11190 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
111a0 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
111b0 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
111c0 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
111d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
111e0 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
111f0 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
11200 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
11210 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
11220 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
11230 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
11240 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
11250 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
11260 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
11270 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
11280 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
11290 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
112a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
112b0 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
112c0 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
112d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
112e0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
112f0 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
11300 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
11310 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
11320 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
11330 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
11340 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
11350 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
11360 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
11370 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
11380 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
11390 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
113a0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
113b0 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
113c0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
113d0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
113e0 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
113f0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11400 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
11410 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
11420 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
11430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11440 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
11450 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
11460 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
11470 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
11480 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
11490 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
114a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
114b0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
114c0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
114d0 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
114e0 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
114f0 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
11500 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
11510 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
11520 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
11530 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
11540 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
11550 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
11560 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
11570 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
11580 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
11590 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
115a0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
115b0 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
115c0 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
115d0 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
115e0 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
115f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
11600 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
11610 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
11620 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
11630 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
11640 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
11650 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
11660 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11670 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
11680 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
11690 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
116a0 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
116b0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
116c0 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
116d0 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
116e0 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
116f0 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
11700 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
11710 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
11720 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
11730 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
11740 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
11750 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
11760 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
11770 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
11780 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
11790 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
117a0 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
117b0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
117c0 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
117d0 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
117e0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
117f0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
11800 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
11810 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11820 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
11830 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
11840 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
11850 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
11860 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
11870 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
11880 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
11890 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
118a0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
118b0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
118c0 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
118d0 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
118e0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
118f0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
11900 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
11910 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
11920 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
11930 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
11940 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
11950 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
11960 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
11970 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
11980 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11990 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
119a0 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
119b0 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
119c0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
119d0 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
119e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
119f0 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
11a00 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
11a10 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
11a20 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
11a30 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
11a40 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
11a50 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
11a60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11a70 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
11a80 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
11a90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
11aa0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
11ab0 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
11ac0 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
11ad0 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
11ae0 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
11af0 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
11b00 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
11b10 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
11b20 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
11b30 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
11b40 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
11b50 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f  y allocator.  Fo
11b60 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
11b70 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
11b80 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
11b90 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
11ba0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
11bb0 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
11bc0 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
11bd0 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
11be0 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
11bf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
11c00 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
11c10 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
11c20 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
11c30 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
11c40 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
11c50 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
11c60 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
11c70 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
11c80 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
11c90 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
11ca0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
11cb0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
11cc0 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
11cd0 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
11ce0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
11cf0 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
11d00 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
11d10 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
11d20 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
11d30 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
11d40 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
11d50 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
11d60 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
11d70 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
11d80 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
11d90 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
11da0 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
11db0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
11dc0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
11dd0 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
11de0 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
11df0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11e00 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
11e10 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
11e20 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
11e30 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
11e40 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
11e50 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
11e60 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
11e70 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
11e80 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
11e90 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
11ea0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
11eb0 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
11ec0 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
11ed0 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
11ee0 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
11ef0 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
11f00 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
11f10 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
11f20 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
11f30 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
11f40 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
11f50 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
11f60 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
11f70 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
11f80 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
11f90 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
11fa0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11fb0 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
11fc0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
11fd0 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
11fe0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11ff0 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
12000 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
12010 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
12020 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
12030 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
12040 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
12050 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
12060 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
12070 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
12080 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
12090 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
120a0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
120b0 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
120c0 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
120d0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
120e0 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
120f0 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
12100 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
12110 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
12120 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
12130 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
12140 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
12150 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
12160 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
12170 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
12180 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
12190 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
121a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
121b0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
121c0 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
121d0 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
121e0 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
121f0 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
12200 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12210 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
12220 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
12230 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
12240 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
12250 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
12260 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
12270 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
12280 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12290 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
122a0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
122b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
122c0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
122d0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
122e0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
122f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12300 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
12310 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
12320 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
12330 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
12340 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
12350 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
12360 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
12370 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
12380 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
12390 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
123a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
123b0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
123c0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
123d0 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
123e0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
123f0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
12400 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
12410 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
12420 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
12430 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
12440 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12450 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
12460 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
12470 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12480 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
12490 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
124a0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
124b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
124c0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
124d0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
124e0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
124f0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
12500 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
12510 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
12520 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
12530 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
12540 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
12550 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
12560 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
12570 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
12580 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
12590 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
125a0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
125b0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
125c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
125d0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
125e0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
125f0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12600 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12610 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
12620 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
12630 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
12640 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
12650 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
12660 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
12670 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
12680 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
12690 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
126a0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
126b0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
126c0 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
126d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
126e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
126f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12700 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
12710 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12720 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
12730 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
12740 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12750 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
12760 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12770 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
12780 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
12790 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
127a0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
127b0 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
127c0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
127d0 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
127e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
127f0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
12800 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
12810 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
12820 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
12830 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
12840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
12850 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12860 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
12870 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
12880 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
12890 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
128a0 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
128b0 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
128c0 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
128d0 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
128e0 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
128f0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
12900 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
12910 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
12920 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
12930 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12940 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12950 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12960 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12970 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12980 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12990 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
129a0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
129b0 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
129c0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
129d0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
129e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
129f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
12a00 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
12a10 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
12a20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12a30 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
12a40 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
12a50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12a70 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
12a80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
12a90 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
12aa0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
12ab0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
12ac0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
12ad0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
12ae0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
12af0 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
12b00 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
12b10 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
12b20 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
12b30 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
12b40 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
12b50 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
12b60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12b70 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12b80 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
12b90 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
12ba0 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
12bb0 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
12bc0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12bd0 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
12be0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
12bf0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
12c00 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
12c10 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
12c20 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
12c30 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
12c40 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12c50 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
12c60 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
12c70 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
12c80 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
12c90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12ca0 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
12cb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12cc0 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
12cd0 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
12ce0 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
12cf0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12d00 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12d10 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12d20 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12d30 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12d40 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12d50 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
12d60 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
12d70 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
12d80 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12d90 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
12da0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12db0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12dc0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
12dd0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
12de0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
12df0 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
12e00 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12e10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12e20 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
12e30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12e40 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
12e50 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
12e60 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12e70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12e80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12e90 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
12ea0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
12eb0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
12ec0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12ed0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
12ee0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
12ef0 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
12f00 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
12f10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12f20 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
12f30 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
12f40 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
12f50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12f60 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
12f70 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
12f80 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
12f90 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
12fa0 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
12fb0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12fc0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12fd0 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
12fe0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
12ff0 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
13000 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
13010 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13020 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
13030 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13040 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
13050 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
13060 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13070 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
13080 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13090 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
130a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
130b0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
130c0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
130d0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
130e0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
130f0 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
13100 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
13110 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
13120 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
13130 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13140 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
13150 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
13160 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
13170 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
13180 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13190 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
131a0 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
131b0 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
131c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
131d0 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
131e0 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
131f0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
13200 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13210 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
13220 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
13230 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13240 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
13250 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13260 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74  IG_MEMSTATUS opt
13270 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
13280 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
13290 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70  e int,.** interp
132a0 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
132b0 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
132c0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
132d0 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a  e collection of.
132e0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
132f0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e  tion statistics.
13300 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
13310 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
13320 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  tics are.** disa
13330 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
13340 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
13350 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
13360 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
13370 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
13380 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
13390 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
133a0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
133b0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
133c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
133d0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
133e0 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
133f0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
13400 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  us64()].**   </u
13410 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
13420 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
13430 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
13440 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
13450 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
13460 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
13470 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
13480 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
13490 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
134a0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
134b0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
134c0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
134d0 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
134e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
134f0 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
13500 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13510 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
13520 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
13530 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70  ONFIG_SCRATCH op
13540 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
13550 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
13560 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51  uffer.** that SQ
13570 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
13580 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
13590 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68    ^(There are th
135a0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ree arguments.**
135b0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
135c0 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f  G_SCRATCH:  A po
135d0 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a  inter an 8-byte.
135e0 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  ** aligned memor
135f0 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68  y buffer from wh
13600 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20  ich the scratch 
13610 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
13620 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
13630 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
13640 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
13650 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
13660 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
13670 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
13680 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a  ocations (N).)^.
13690 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
136a0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
136b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
136c0 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
136d0 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
136e0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
136f0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
13700 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65  ite will not use
13710 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73   more than one s
13720 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
13730 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53  er thread..** ^S
13740 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
13750 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74   request a scrat
13760 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
13770 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
13780 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
13790 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a  ase page size..*
137a0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  * ^If SQLite nee
137b0 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
137c0 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
137d0 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
137e0 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
137f0 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
13800 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
13810 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
13820 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
13830 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
13840 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
13850 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  .<p>.** ^When th
13860 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72  e application pr
13870 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e  ovides any amoun
13880 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d  t of scratch mem
13890 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ory using.** SQL
138a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
138b0 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64  CH, SQLite avoid
138c0 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61  s unnecessary la
138d0 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rge.** [sqlite3_
138e0 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f  malloc|heap allo
138f0 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69  cations]..** Thi
13900 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73  s can help [Robs
13910 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74  on proof|prevent
13920 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13930 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65  on failures] due
13940 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67   to heap.** frag
13950 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77  mentation in low
13960 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64  -memory embedded
13970 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64   systems..** </d
13980 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13990 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
139a0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
139b0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
139c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
139d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
139e0 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f  _PAGECACHE optio
139f0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65  n specifies a me
13a00 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61  mory pool.** tha
13a10 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
13a20 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
13a30 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
13a40 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
13a50 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
13a60 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
13a70 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
13a80 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20  ion option is a 
13a90 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c  no-op if an appl
13aa0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
13ab0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
13ac0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
13ad0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
13ae0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13af0 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65  CACHE2]..** ^The
13b00 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
13b10 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
13b20 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13b30 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
13b40 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
13b50 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c  d memory (pMem),
13b60 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
13b70 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  h page cache lin
13b80 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  e (sz),.** and t
13b90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63  he number of cac
13ba0 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a  he lines (N)..**
13bb0 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
13bc0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
13bd0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
13be0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
13bf0 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
13c00 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
13c10 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
13c20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
13c30 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
13c40 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
13c50 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
13c60 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
13c70 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
13c80 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
13c90 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49  ined using [SQLI
13ca0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13cb0 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20  _HDRSZ]..** ^It 
13cc0 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
13cd0 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
13ce0 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f  ed memory,.** fo
13cf0 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74  r the sz paramet
13d00 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20  er to be larger 
13d10 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20  than necessary. 
13d20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67   The pMem.** arg
13d30 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69  ument must be ei
13d40 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
13d50 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ter or a pointer
13d60 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
13d70 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f   aligned block o
13d80 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  f memory of at l
13d90 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c  east sz*N bytes,
13da0 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75   otherwise.** su
13db0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
13dc0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
13dd0 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73  ** ^When pMem is
13de0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
13df0 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f  e will strive to
13e00 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
13e10 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73  provided.** to s
13e20 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68  atisfy page cach
13e30 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67  e needs, falling
13e40 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65   back to [sqlite
13e50 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a  3_malloc()] if.*
13e60 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c  * a page cache l
13e70 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68  ine is larger th
13e80 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69  an sz bytes or i
13e90 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65  f all of the pMe
13ea0 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65  m buffer.** is e
13eb0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66  xhausted..** ^If
13ec0 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e   pMem is NULL an
13ed0 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  d N is non-zero,
13ee0 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62   then each datab
13ef0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
13f00 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61  * does an initia
13f10 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f  l bulk allocatio
13f20 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  n for page cache
13f30 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20   memory.** from 
13f40 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13f50 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f  )] sufficient fo
13f60 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20  r N cache lines 
13f70 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
13f80 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a   or.** of -1024*
13f90 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20  N bytes if N is 
13fa0 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20  negative, . ^If 
13fb0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
13fc0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
13fd0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
13fe0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
13ff0 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c  d by the initial
14000 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  .** allocation, 
14010 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73  then SQLite goes
14020 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
14030 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c  loc()] separatel
14040 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64  y for each.** ad
14050 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c  ditional cache l
14060 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ine. </dd>.**.**
14070 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14080 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
14090 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
140a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
140b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
140c0 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
140d0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
140e0 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
140f0 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
14100 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
14110 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
14120 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14130 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
14140 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
14150 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
14160 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a  IG_SCRATCH] and.
14170 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
14180 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
14190 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
141a0 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
141b0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
141c0 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
141d0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
141e0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
141f0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
14200 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
14210 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
14220 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
14230 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
14240 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
14250 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
14260 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
14270 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14280 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
14290 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
142a0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
142b0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
142c0 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
142d0 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
142e0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
142f0 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
14300 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
14310 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14320 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
14330 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
14340 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
14350 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
14360 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14370 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
14380 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
14390 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
143a0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
143b0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
143c0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
143d0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
143e0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
143f0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
14400 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
14410 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
14420 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
14430 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
14440 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
14450 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
14460 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
14470 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
14480 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
14490 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
144a0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
144b0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
144c0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
144d0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
144e0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
144f0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
14500 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
14510 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
14520 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
14530 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
14540 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
14550 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
14560 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
14570 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14580 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
14590 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
145a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
145b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
145c0 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
145d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
145e0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
145f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
14600 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14610 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
14620 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14630 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
14640 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
14650 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
14660 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
14670 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
14680 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
14690 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
146a0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
146b0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
146c0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
146d0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
146e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
146f0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14700 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
14710 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
14720 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
14730 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
14740 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
14750 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
14760 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
14770 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
14780 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
14790 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
147a0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
147b0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
147c0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
147d0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
147e0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
147f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
14800 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
14810 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
14820 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14830 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
14840 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
14850 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14870 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
14880 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
14890 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
148a0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
148b0 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
148c0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
148d0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
148e0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
148f0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
14900 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14910 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
14920 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
14930 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
14940 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
14950 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
14960 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
14970 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
14980 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
14990 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
149a0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
149b0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
149c0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
149d0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
149e0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
149f0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
14a00 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
14a10 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
14a20 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
14a30 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
14a40 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14a50 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
14a60 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
14a70 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
14a80 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
14a90 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14aa0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
14ab0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
14ac0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
14ad0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
14ae0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
14af0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14b00 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
14b10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14b20 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
14b30 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
14b40 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
14b50 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
14b60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14b70 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14b80 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
14b90 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
14ba0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14bb0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14bc0 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
14bd0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
14be0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
14bf0 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
14c00 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
14c10 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
14c20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
14c30 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
14c40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14c50 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
14c60 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
14c70 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
14c80 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
14c90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
14ca0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
14cb0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
14cc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
14cd0 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
14ce0 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
14cf0 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
14d00 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
14d10 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
14d20 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
14d30 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
14d40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
14d50 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
14d60 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
14d70 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
14d80 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14d90 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
14da0 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
14db0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14dc0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
14dd0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14de0 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
14df0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14e00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14e10 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
14e20 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14e30 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
14e40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14e50 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
14e60 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14e70 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
14e80 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
14e90 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
14ea0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
14eb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14ec0 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
14ed0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
14ee0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
14ef0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14f00 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
14f10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14f20 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
14f30 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14f40 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
14f50 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14f60 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14f70 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14f80 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14f90 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
14fa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14fb0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
14fc0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14fd0 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
14fe0 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
14ff0 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
15000 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
15010 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
15020 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
15030 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15040 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
15050 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
15060 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
15070 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
15080 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
15090 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
150a0 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
150b0 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
150c0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
150d0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
150e0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
150f0 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
15100 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
15110 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
15120 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
15130 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
15140 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
15150 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
15160 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
15170 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
15180 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
15190 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
151a0 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
151b0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
151c0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
151d0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
151e0 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
151f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
15200 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
15210 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
15220 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
15230 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
15240 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15250 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
15260 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
15270 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
15280 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15290 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
152a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
152b0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
152c0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
152d0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
152e0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
152f0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
15300 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
15310 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
15320 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
15330 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
15340 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
15350 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
15360 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
15370 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
15380 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
15390 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
153a0 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
153b0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
153c0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
153d0 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
153e0 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
153f0 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
15400 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
15410 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
15420 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
15430 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
15440 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
15450 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
15460 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
15470 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
15480 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
15490 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
154a0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
154b0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
154c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
154d0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
154e0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
154f0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
15500 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15510 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
15520 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15530 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
15540 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15550 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
15560 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15570 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
15580 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
15590 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
155a0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
155b0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
155c0 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
155d0 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
155e0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
155f0 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
15600 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
15610 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
15620 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
15630 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
15640 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
15650 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
15660 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
15670 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
15680 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
15690 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
156a0 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
156b0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
156c0 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
156d0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
156e0 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
156f0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
15700 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
15710 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
15720 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
15730 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
15740 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
15750 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
15760 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
15770 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
15780 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
15790 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
157a0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
157b0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
157c0 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
157d0 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
157e0 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
157f0 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
15800 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
15810 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
15820 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
15830 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
15840 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
15850 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
15860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15870 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
15880 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15890 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
158a0 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
158b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
158c0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
158d0 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
158e0 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
158f0 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
15900 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
15910 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
15920 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
15930 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
15940 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
15950 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
15960 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
15970 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
15980 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
15990 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
159a0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
159b0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
159c0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
159d0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
159e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
159f0 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
15a00 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
15a10 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
15a20 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
15a30 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
15a40 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
15a50 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
15a60 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
15a70 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
15a80 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
15a90 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
15aa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
15ab0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
15ac0 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
15ad0 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
15ae0 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
15af0 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
15b00 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
15b10 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
15b20 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
15b30 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
15b40 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
15b50 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
15b60 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
15b70 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
15b80 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15b90 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
15ba0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15bb0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
15bc0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15bd0 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
15be0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15bf0 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
15c00 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
15c10 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
15c20 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
15c30 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
15c40 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
15c50 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
15c60 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
15c70 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
15c80 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
15c90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15ca0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
15cb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
15cc0 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
15cd0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
15ce0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
15cf0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15d00 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
15d10 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
15d20 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
15d30 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
15d40 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15d50 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
15d60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
15d70 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
15d80 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
15d90 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
15da0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
15db0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
15dc0 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
15dd0 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
15de0 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
15df0 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
15e00 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
15e10 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
15e20 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
15e30 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
15e40 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
15e50 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
15e60 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15e70 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
15e80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15e90 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
15ea0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
15eb0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
15ec0 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
15ed0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
15ee0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
15ef0 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
15f00 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
15f10 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
15f20 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
15f30 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
15f40 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
15f50 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
15f60 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
15f70 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
15f80 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
15f90 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
15fa0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
15fb0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
15fc0 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
15fd0 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
15fe0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
15ff0 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
16000 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
16010 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
16020 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
16030 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
16040 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
16050 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
16060 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
16070 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
16080 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
16090 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
160a0 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
160b0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
160c0 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
160d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
160e0 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
160f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16100 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
16110 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
16120 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
16130 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
16140 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
16150 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
16160 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
16170 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
16180 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
16190 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
161a0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
161b0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
161c0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
161d0 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
161e0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
161f0 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
16200 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
16210 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16220 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
16230 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
16240 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
16250 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
16260 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
16270 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
16280 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
16290 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
162a0 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
162b0 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
162c0 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
162d0 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
162e0 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
162f0 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
16300 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
16310 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
16320 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
16330 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
16340 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16350 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
16360 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
16370 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
16380 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
16390 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
163a0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
163b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
163c0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
163d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
163e0 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
163f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16400 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
16410 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
16420 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16430 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
16440 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
16450 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
16460 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
16470 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
16480 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
16490 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
164a0 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
164b0 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
164c0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
164d0 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
164e0 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
164f0 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
16500 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
16510 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
16520 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
16530 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
16540 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
16550 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
16560 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16570 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
16580 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
16590 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
165a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
165b0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
165c0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
165d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
165e0 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
165f0 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
16600 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
16610 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
16620 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
16630 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
16640 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
16650 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
16660 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
16670 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
16680 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
16690 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
166a0 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
166b0 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
166c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
166d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
166e0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
166f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16700 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
16710 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
16720 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
16730 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16740 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
16750 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
16760 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
16770 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
16780 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
16790 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
167a0 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
167b0 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
167c0 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
167d0 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
167e0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
167f0 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
16800 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16810 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
16820 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
16830 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
16840 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
16850 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
16860 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
16870 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
16880 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
16890 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
168a0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
168b0 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
168c0 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
168d0 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
168e0 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
168f0 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
16900 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
16910 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
16920 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  lue..**.** [[SQL
16930 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
16940 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c  RNL_SPILL]].** <
16950 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16960 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a  _STMTJRNL_SPILL.
16970 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
16980 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
16990 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20  NL_SPILL option 
169a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
169b0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
169c0 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73  * becomes the [s
169d0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
169e0 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20  ] spill-to-disk 
169f0 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20  threshold.  .** 
16a00 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [Statement journ
16a10 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e  als] are held in
16a20 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68   memory until th
16a30 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74  eir size (in byt
16a40 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74  es).** exceeds t
16a50 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61  his threshold, a
16a60 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68  t which point th
16a70 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74  ey are written t
16a80 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66  o disk..** Or if
16a90 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69   the threshold i
16aa0 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20  s -1, statement 
16ab0 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77  journals are alw
16ac0 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c  ays held.** excl
16ad0 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72  usively in memor
16ae0 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79  y..** Since many
16af0 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
16b00 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65  als never become
16b10 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20   large, setting 
16b20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72  the spill.** thr
16b30 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75  eshold to a valu
16b40 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20  e such as 64KiB 
16b50 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75  can greatly redu
16b60 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ce the amount of
16b70 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64  .** I/O required
16b80 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74   to support stat
16b90 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a  ement rollback..
16ba0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
16bb0 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65  alue for this se
16bc0 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c  tting is control
16bd0 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  led by the.** [S
16be0 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53  QLITE_STMTJRNL_S
16bf0 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  PILL] compile-ti
16c00 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f  me option..** </
16c10 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
16c20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
16c30 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
16c40 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
16c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
16c60 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
16c70 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
16c80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16c90 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
16ca0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16cb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16cc0 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
16cd0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
16ce0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
16cf0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16d00 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
16d10 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
16d20 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
16d30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16d40 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
16d50 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
16d60 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
16d70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16d80 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
16d90 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
16da0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
16db0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16dc0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
16dd0 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
16de0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
16df0 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
16e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16e10 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
16e20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
16e30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16e40 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
16e50 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
16e60 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
16e70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16e80 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
16e90 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
16ea0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16eb0 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
16ec0 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
16ed0 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
16ee0 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
16ef0 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
16f00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16f10 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
16f20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
16f30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16f40 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
16f50 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   14  /* no-op */
16f60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16f70 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16f80 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70      15  /* no-op
16f90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16fa0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
16fb0 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
16fc0 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
16fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16fe0 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
16ff0 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   17  /* int */.#
17000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17010 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20  NFIG_PCACHE2    
17020 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33    18  /* sqlite3
17030 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
17040 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17050 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
17060 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73  ACHE2   19  /* s
17070 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
17080 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
17090 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
170a0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
170b0 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20  SCAN 20  /* int 
170c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
170d0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20  E_CONFIG_SQLLOG 
170e0 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71        21  /* xSq
170f0 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  llog, void* */.#
17100 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17110 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  NFIG_MMAP_SIZE  
17120 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33    22  /* sqlite3
17130 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f  _int64, sqlite3_
17140 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65  int64 */.#define
17150 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
17160 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20  IN32_HEAPSIZE   
17170 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42     23  /* int nB
17180 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  yte */.#define S
17190 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
171a0 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20  CHE_HDRSZ       
171b0 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a   24  /* int *psz
171c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
171d0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
171e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
171f0 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e    /* unsigned in
17200 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69  t szPma */.#defi
17210 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17220 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20  _STMTJRNL_SPILL 
17230 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e 74 20       26  /* int 
17240 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nByte */../*.** 
17250 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
17260 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
17270 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
17280 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
17290 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
172a0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
172b0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
172c0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
172d0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
172e0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
172f0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
17300 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17310 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
17320 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
17330 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
17340 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
17350 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
17360 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
17370 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
17380 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
17390 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
173a0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
173b0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
173c0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
173d0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
173e0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
173f0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
17400 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
17410 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
17420 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
17430 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
17440 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
17450 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
17460 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
17470 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
17480 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
17490 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
174a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
174b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
174c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
174d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
174e0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
174f0 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
17500 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
17510 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
17520 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
17530 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
17540 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
17550 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
17560 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
17570 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
17580 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
17590 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
175a0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
175b0 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
175c0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
175d0 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
175e0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
175f0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
17600 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
17610 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
17620 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
17630 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
17640 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
17650 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
17660 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
17670 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
17680 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
17690 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
176a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
176b0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
176c0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
176d0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
176e0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
176f0 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
17700 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
17710 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
17720 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
17730 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
17740 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
17750 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
17760 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
17770 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
17780 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
17790 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
177a0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
177b0 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
177c0 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
177d0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
177e0 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
177f0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
17800 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
17810 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
17820 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
17830 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
17840 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
17850 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
17860 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
17870 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
17880 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
17890 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
178a0 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
178b0 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
178c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
178d0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
178e0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
178f0 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
17900 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
17910 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
17920 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
17930 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
17940 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
17950 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
17960 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
17970 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
17980 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
17990 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
179a0 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
179b0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
179c0 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
179d0 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
179e0 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
179f0 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
17a00 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
17a10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17a20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17a30 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
17a40 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
17a50 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
17a60 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
17a70 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
17a80 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
17a90 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
17aa0 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
17ab0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
17ac0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
17ad0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
17ae0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
17af0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
17b00 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
17b10 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
17b20 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
17b30 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
17b40 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
17b50 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
17b60 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
17b70 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17b80 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
17b90 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
17ba0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
17bb0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
17bc0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
17bd0 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
17be0 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
17bf0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
17c00 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
17c10 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
17c20 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
17c30 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
17c40 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
17c50 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
17c60 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
17c70 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
17c80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17c90 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
17ca0 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
17cb0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17cc0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17cd0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
17ce0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
17cf0 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
17d00 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
17d10 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
17d20 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
17d30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
17d40 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
17d50 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
17d60 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
17d70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
17d80 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
17d90 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
17da0 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
17db0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
17dc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
17dd0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
17de0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
17df0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
17e00 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
17e10 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
17e20 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
17e30 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
17e40 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
17e50 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
17e60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
17e70 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
17e80 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
17e90 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
17ea0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
17eb0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
17ec0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
17ed0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
17ee0 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e  NABLE_FTS3_TOKEN
17ef0 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZER</dt>.** <dd
17f00 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
17f10 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
17f20 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
17f30 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  two-argument.** 
17f40 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b  version of the [
17f50 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
17f60 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68  ] function which
17f70 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   is part of the.
17f80 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74  ** [FTS3] full-t
17f90 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69 6e  ext search engin
17fa0 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20  e extension..** 
17fb0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17fc0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17fd0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17fe0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17ff0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
18000 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
18010 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
18020 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74  er() or.** posit
18030 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66 74  ive to enable ft
18040 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f  s3_tokenizer() o
18050 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
18060 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a  ave the setting.
18070 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ** unchanged..**
18080 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18090 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
180a0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
180b0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
180c0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
180d0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
180e0 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69  ther fts3_tokeni
180f0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
18100 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
18110 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
18120 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
18130 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
18140 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
18150 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
18160 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67   the new setting
18170 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
18180 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
18190 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
181a0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f  CONFIG_ENABLE_LO
181b0 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74  AD_EXTENSION</dt
181c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
181d0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
181e0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
181f0 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ble the [sqlite3
18200 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18210 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
18220 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66  independently of
18230 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e   the [load_exten
18240 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63  sion()] SQL func
18250 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  tion..** The [sq
18260 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
18270 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41  d_extension()] A
18280 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  PI enables or di
18290 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a  sables both the.
182a0 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65  ** C-API [sqlite
182b0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
182c0 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ()] and the SQL 
182d0 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65  function [load_e
182e0 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20  xtension()]..** 
182f0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
18300 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
18310 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65  rguments..** Whe
18320 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
18330 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74  ment to this int
18340 65 72 66 61 63 65 20 69 73 20 31 2c 20 74 68 65  erface is 1, the
18350 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49  n only the C-API
18360 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61   is.** enabled a
18370 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
18380 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61  ion remains disa
18390 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66 69  bled.  If the fi
183a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  rst argument to.
183b0 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ** this interfac
183c0 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74  e is 0, then bot
183d0 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20  h the C-API and 
183e0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
183f0 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a   are disabled..*
18400 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61  * If the first a
18410 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74  rgument is -1, t
18420 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61  hen no changes a
18430 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65  re made to state
18440 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a   of either the.*
18450 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53  * C-API or the S
18460 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  QL function..** 
18470 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18480 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
18490 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
184a0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
184b0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
184c0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
184d0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  her [sqlite3_loa
184e0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69  d_extension()] i
184f0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64  nterface.** is d
18500 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
18510 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ed following thi
18520 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
18530 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
18540 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70  y.** be a NULL p
18550 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68  ointer, in which
18560 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65   case the new se
18570 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
18580 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c  orted back..** <
18590 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
185a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d  QLITE_DBCONFIG_M
185b0 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a  AINDBNAME</dt>.*
185c0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
185d0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
185e0 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65 20 6f  hange the name o
185f0 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64 61 74  f the "main" dat
18600 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e  abase.** schema.
18610 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72 67 75    ^The sole argu
18620 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
18630 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20  r to a constant 
18640 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77  UTF8 string.** w
18650 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65  hich will become
18660 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d 61 20   the new schema 
18670 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  name in place of
18680 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74   "main".  ^SQLit
18690 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61  e.** does not ma
186a0 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ke a copy of the
186b0 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65 6d 61   new main schema
186c0 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f   name string, so
186d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
186e0 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
186f0 74 68 61 74 20 74 68 65 20 61 72 67 75 6d 65 6e  that the argumen
18700 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  t passed into th
18710 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70 74 69  is DBCONFIG opti
18720 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65 64 0a  on is unchanged.
18730 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ** until after t
18740 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18750 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
18760 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
18770 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18780 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f  G_NO_CKPT_ON_CLO
18790 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  SE</dt>.** <dd> 
187a0 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 61 20  Usually, when a 
187b0 64 61 74 61 62 61 73 65 20 69 6e 20 77 61 6c 20  database in wal 
187c0 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64 20 6f  mode is closed o
187d0 72 20 64 65 74 61 63 68 65 64 20 66 72 6f 6d 20  r detached from 
187e0 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68  a .** database h
187f0 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20 63 68  andle, SQLite ch
18800 65 63 6b 73 20 69 66 20 74 68 69 73 20 77 69 6c  ecks if this wil
18810 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 72  l mean that ther
18820 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a  e are now no .**
18830 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 74 20   connections at 
18840 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74 61 62  all to the datab
18850 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74 20 70  ase. If so, it p
18860 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63 6b 70  erforms a checkp
18870 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 74 69  oint .** operati
18880 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73 69 6e  on before closin
18890 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  g the connection
188a0 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d 61  . This option ma
188b0 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20  y be used to.** 
188c0 6f 76 65 72 72 69 64 65 20 74 68 69 73 20 62 65  override this be
188d0 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66 69 72  haviour. The fir
188e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  st parameter pas
188f0 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65 72  sed to this oper
18900 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20 69  ation.** is an i
18910 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a 65 72  nteger - non-zer
18920 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 63 68 65  o to disable che
18930 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73  ckpoints-on-clos
18940 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68 65 0a  e, or zero (the.
18950 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f 20 65  ** default) to e
18960 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 68 65 20  nable them. The 
18970 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18980 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18990 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 69   an integer.** i
189a0 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 72 69  nto which is wri
189b0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
189c0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
189d0 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63  checkpoints-on-c
189e0 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62 65 65  lose.** have bee
189f0 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30 20 69  n disabled - 0 i
18a00 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 64  f they are not d
18a10 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20 74 68  isabled, 1 if th
18a20 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e  ey are..** </dd>
18a30 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
18a40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18a50 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41  BCONFIG_MAINDBNA
18a60 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 31 30  ME            10
18a70 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72  00 /* const char
18a80 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18a90 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
18aa0 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20  KASIDE          
18ab0 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a     1001 /* void*
18ac0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
18ad0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18ae0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
18af0 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f            1002 /
18b00 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
18b10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18b20 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
18b30 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33  GGER        1003
18b40 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18b50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18b60 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
18b70 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30  TS3_TOKENIZER 10
18b80 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  04 /* int int* *
18b90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18ba0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18bb0 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20  _LOAD_EXTENSION 
18bc0 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1005 /* int int*
18bd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18be0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
18bf0 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20  KPT_ON_CLOSE    
18c00 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e    1006 /* int in
18c10 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
18c20 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
18c30 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
18c40 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
18c50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
18c60 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
18c70 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
18c80 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
18c90 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
18ca0 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
18cb0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
18cc0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
18cd0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
18ce0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
18cf0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
18d00 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
18d10 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
18d20 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
18d30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
18d40 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
18d50 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
18d60 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
18d70 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
18d80 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
18d90 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
18da0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
18db0 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74  ry in most SQLit
18dc0 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74  e tables (except
18dd0 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f   for [WITHOUT RO
18de0 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20  WID] tables).** 
18df0 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
18e00 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
18e10 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
18e20 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
18e30 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
18e40 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
18e50 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
18e60 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
18e70 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
18e80 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
18e90 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
18ea0 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
18eb0 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
18ec0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
18ed0 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
18ee0 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
18ef0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
18f00 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
18f10 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
18f20 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
18f30 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
18f40 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
18f50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61   ^The sqlite3_la
18f60 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
18f70 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  D) interface ret
18f80 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
18f90 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74   of the .** most
18fa0 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
18fb0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
18fc0 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
18fd0 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
18fe0 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
18ff0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
19000 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20  * ^Inserts into 
19010 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
19020 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72  tables are not r
19030 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  ecorded..** ^If 
19040 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
19050 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77  NSERT]s into row
19060 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76  id tables.** hav
19070 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
19080 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
19090 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a  connection D, .*
190a0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c  * then sqlite3_l
190b0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
190c0 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (D) returns zero
190d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
190e0 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
190f0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
19100 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
19110 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
19120 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
19130 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
19140 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
19150 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
19160 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
19170 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
19180 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
19190 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
191a0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
191b0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
191c0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
191d0 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
191e0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
191f0 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
19200 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
19210 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
19220 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
19230 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
19240 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
19250 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
19260 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
19270 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
19280 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
19290 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
192a0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
192b0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
192c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
192d0 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
192e0 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
192f0 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
19300 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
19310 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
19320 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
19330 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
19340 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
19350 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
19360 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
19370 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
19380 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
19390 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
193a0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
193b0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
193c0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
193d0 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
193e0 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
193f0 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
19400 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
19410 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
19420 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
19430 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
19440 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
19450 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
19460 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
19470 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
19480 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
19490 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
194a0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
194b0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
194c0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
194d0 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
194e0 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
194f0 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
19500 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
19510 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
19520 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
19530 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
19540 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
19550 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19560 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
19570 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
19580 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
19590 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
195a0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
195b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
195c0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
195d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
195e0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
195f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
19600 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
19610 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
19620 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
19630 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
19640 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19650 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
19660 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
19670 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
19680 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
19690 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
196a0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
196b0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
196c0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
196d0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
196e0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
196f0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
19700 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
19710 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
19720 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
19730 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
19740 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
19750 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
19760 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
19770 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e  ows modified, in
19780 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  serted or.** del
19790 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
197a0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
197b0 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
197c0 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  TE or DELETE.** 
197d0 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
197e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
197f0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62  tion specified b
19800 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  y the only param
19810 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74  eter..** ^Execut
19820 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
19830 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
19840 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64  ent does not mod
19850 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  ify the value.**
19860 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
19870 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
19880 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  * ^Only changes 
19890 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79  made directly by
198a0 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
198b0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
198c0 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63  atement are.** c
198d0 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69  onsidered - auxi
198e0 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
198f0 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20  used by [CREATE 
19900 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
19910 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67  rs], .** [foreig
19920 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f  n key actions] o
19930 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  r [REPLACE] cons
19940 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
19950 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  n are not counte
19960 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65  d..** .** Change
19970 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
19980 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
19990 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44   by .** [INSTEAD
199a0 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e   OF trigger | IN
199b0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
199c0 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
199d0 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a  ed. ^The value .
199e0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
199f0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19a00 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
19a10 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  er an INSERT, UP
19a20 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45  DATE or .** DELE
19a30 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e  TE statement run
19a40 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c   on a view is al
19a50 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20  ways zero. Only 
19a60 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20  changes made to 
19a70 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20  real .** tables 
19a80 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
19a90 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f  ** Things are mo
19aa0 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69  re complicated i
19ab0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  f the sqlite3_ch
19ac0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
19ad0 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   is.** executed 
19ae0 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20  while a trigger 
19af0 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69  program is runni
19b00 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70  ng. This may hap
19b10 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72  pen if the.** pr
19b20 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b  ogram uses the [
19b30 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
19b40 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73  nction], or if s
19b50 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61  ome other callba
19b60 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ck.** function i
19b70 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63  nvokes sqlite3_c
19b80 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c  hanges() directl
19b90 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a  y. Essentially:.
19ba0 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  ** .** <ul>.**  
19bb0 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65   <li> ^(Before e
19bc0 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65  ntering a trigge
19bd0 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61  r program the va
19be0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  lue returned by.
19bf0 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65  **        sqlite
19c00 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
19c10 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41  tion is saved. A
19c20 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72  fter the trigger
19c30 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20   program .**    
19c40 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64      has finished
19c50 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76  , the original v
19c60 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64  alue is restored
19c70 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69  .)^.** .**   <li
19c80 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69  > ^(Within a tri
19c90 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63  gger program eac
19ca0 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  h INSERT, UPDATE
19cb0 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20   and DELETE .** 
19cc0 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
19cd0 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20   sets the value 
19ce0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
19cf0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
19d00 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f  *        upon co
19d10 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d  mpletion as norm
19d20 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74  al. Of course, t
19d30 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e  his value will n
19d40 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20  ot include .**  
19d50 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65        any change
19d60 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73  s performed by s
19d70 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20  ub-triggers, as 
19d80 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
19d90 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
19da0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73   value will be s
19db0 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65  aved and restore
19dc0 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62  d after each sub
19dd0 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e  -trigger has run
19de0 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  .)^.** </ul>.** 
19df0 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20  .** ^This means 
19e00 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e  that if the chan
19e10 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
19e20 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20  on (or similar) 
19e30 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  is used.** by th
19e40 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20  e first INSERT, 
19e50 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
19e60 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
19e70 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20  n a trigger, it 
19e80 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
19e90 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65  value as set whe
19ea0 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74  n the calling st
19eb0 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78  atement began ex
19ec0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20  ecuting..** ^If 
19ed0 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68  it is used by th
19ee0 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73  e second or subs
19ef0 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74  equent such stat
19f00 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
19f10 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72  rigger .** progr
19f20 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  am, the value re
19f30 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20  turned reflects 
19f40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
19f50 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74  ws modified by t
19f60 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  he .** previous 
19f70 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
19f80 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
19f90 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
19fa0 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a  me trigger..**.*
19fb0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
19fc0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
19fd0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
19fe0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
19ff0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1a000 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
1a010 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1a020 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1a030 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1a040 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
1a050 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1a060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1a070 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1a080 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1a090 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1a0a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1a0b0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1a0c0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1a0d0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
1a0e0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
1a0f0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1a100 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
1a110 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1a120 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
1a130 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1a140 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1a150 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
1a160 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1a170 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
1a180 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1a190 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
1a1a0 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
1a1b0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
1a1c0 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
1a1d0 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
1a1e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
1a1f0 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
1a200 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
1a210 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
1a220 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
1a230 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
1a240 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1a250 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1a260 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
1a270 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a280 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
1a290 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
1a2a0 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
1a2b0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
1a2c0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1a2d0 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
1a2e0 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
1a2f0 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
1a300 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
1a310 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
1a320 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
1a330 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
1a340 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
1a350 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
1a360 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
1a370 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
1a380 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
1a390 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
1a3a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a3b0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
1a3c0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
1a3d0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
1a3e0 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
1a3f0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1a400 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1a410 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1a420 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
1a430 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1a440 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1a450 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1a460 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1a470 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1a480 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
1a490 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
1a4a0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
1a4b0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
1a4c0 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
1a4d0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1a4e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1a4f0 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
1a500 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
1a510 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ery.** METHOD: s
1a520 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1a530 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
1a540 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
1a550 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1a560 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
1a570 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
1a580 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
1a590 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
1a5a0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
1a5b0 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
1a5c0 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
1a5d0 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
1a5e0 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
1a5f0 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
1a600 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
1a610 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
1a620 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
1a630 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
1a640 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
1a650 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1a660 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
1a670 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
1a680 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
1a690 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
1a6a0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
1a6b0 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
1a6c0 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
1a6d0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1a6e0 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1a6f0 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
1a700 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
1a710 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
1a720 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
1a730 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
1a740 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
1a750 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
1a760 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1a770 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
1a780 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
1a790 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
1a7a0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
1a7b0 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
1a7c0 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
1a7d0 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
1a7e0 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
1a7f0 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
1a800 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
1a810 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
1a820 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
1a830 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
1a840 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
1a850 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
1a860 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
1a870 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
1a880 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
1a890 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
1a8a0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
1a8b0 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
1a8c0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
1a8d0 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
1a8e0 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
1a8f0 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
1a900 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
1a910 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
1a920 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a930 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
1a940 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
1a950 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1a960 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
1a970 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
1a980 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1a990 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
1a9a0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
1a9b0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1a9c0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1a9d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a9e0 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
1a9f0 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
1aa00 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
1aa10 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
1aa20 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
1aa30 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
1aa40 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
1aa50 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1aa60 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1aa70 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
1aa80 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1aa90 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1aaa0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
1aab0 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
1aac0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
1aad0 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
1aae0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
1aaf0 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
1ab00 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1ab10 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
1ab20 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
1ab30 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
1ab40 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1ab50 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
1ab60 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
1ab70 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
1ab80 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1ab90 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1aba0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1abb0 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
1abc0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
1abd0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1abe0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
1abf0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
1ac00 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
1ac10 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
1ac20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
1ac30 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
1ac40 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1ac50 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1ac60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ac70 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1ac80 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1ac90 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1aca0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1acb0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1acc0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1acd0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1ace0 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1acf0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1ad00 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1ad10 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1ad20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1ad30 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1ad40 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1ad50 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1ad60 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1ad70 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1ad80 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1ad90 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1ada0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1adb0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1adc0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1add0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1ade0 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1adf0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1ae00 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1ae10 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1ae20 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1ae30 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1ae40 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1ae50 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1ae60 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1ae70 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1ae80 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1ae90 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1aea0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1aeb0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1aec0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1aed0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1aee0 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1aef0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1af00 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1af10 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1af20 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1af30 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1af40 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1af50 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1af60 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1af70 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1af80 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1af90 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1afa0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1afb0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1afc0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1afd0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1afe0 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1aff0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1b000 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1b010 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1b020 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1b030 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1b040 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1b050 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1b060 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1b070 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1b080 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1b090 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1b0a0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1b0b0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1b0c0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1b0d0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1b0e0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1b0f0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1b100 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1b110 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1b120 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1b130 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1b140 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1b150 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1b160 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1b170 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1b180 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1b190 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1b1a0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1b1b0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1b1c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1b1d0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1b1e0 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1b1f0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1b200 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1b210 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1b220 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1b230 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1b240 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1b250 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1b260 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1b270 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1b280 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1b290 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1b2a0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
1b2b0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b2c0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1b2d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1b2e0 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
1b2f0 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
1b300 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
1b310 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
1b320 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
1b330 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
1b340 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79   KEYWORDS: {busy
1b350 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
1b360 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72  k} {busy handler
1b370 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
1b380 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
1b390 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1b3a0 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74  dler(D,X,P) rout
1b3b0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
1b3c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ack function X.*
1b3d0 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  * that might be 
1b3e0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
1b3f0 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
1b400 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
1b410 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1b420 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1b430 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
1b440 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1b450 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65  onnection] D whe
1b460 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  n another thread
1b470 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
1b480 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63  as the table loc
1b490 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ked..** The sqli
1b4a0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1b4b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1b4c0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1b4d0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  t.** [sqlite3_bu
1b4e0 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e  sy_timeout()] an
1b4f0 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  d [PRAGMA busy_t
1b500 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  imeout]..**.** ^
1b510 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1b520 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
1b530 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
1b540 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1b550 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
1b560 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
1b570 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
1b580 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
1b590 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
1b5a0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1b5b0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1b5c0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
1b5d0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1b5e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1b5f0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
1b600 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
1b610 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
1b620 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
1b630 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1b640 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
1b650 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
1b660 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1b670 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
1b680 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
1b690 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
1b6a0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
1b6b0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1b6c0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
1b6d0 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ked previously f
1b6e0 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
1b6f0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
1b700 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
1b710 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
1b720 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
1b730 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
1b740 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
1b750 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1b760 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
1b770 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   is returned.** 
1b780 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1b790 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  on..** ^If the c
1b7a0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1b7b0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
1b7c0 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
1b7d0 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  * is made to acc
1b7e0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1b7f0 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
1b800 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
1b810 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
1b820 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
1b830 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
1b840 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
1b850 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
1b860 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
1b870 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
1b880 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
1b890 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
1b8a0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
1b8b0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
1b8c0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
1b8d0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
1b8e0 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
1b8f0 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68  E_BUSY].** to th
1b900 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e  e application in
1b910 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
1b920 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68  g the .** busy h
1b930 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
1b940 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
1b950 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
1b960 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1b970 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
1b980 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
1b990 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
1b9a0 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
1b9b0 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
1b9c0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1b9d0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
1b9e0 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
1b9f0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
1ba00 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
1ba10 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
1ba20 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
1ba30 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
1ba40 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1ba50 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
1ba60 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1ba70 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
1ba80 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
1ba90 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1baa0 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
1bab0 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
1bac0 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
1bad0 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
1bae0 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
1baf0 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
1bb00 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
1bb10 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1bb20 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
1bb30 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
1bb40 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
1bb50 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
1bb60 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
1bb70 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
1bb80 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
1bb90 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
1bba0 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
1bbb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
1bbc0 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
1bbd0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
1bbe0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1bbf0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1bc00 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
1bc10 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
1bc20 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1bc30 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
1bc40 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
1bc50 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
1bc60 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1bc70 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
1bc80 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
1bc90 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1bca0 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20  imeout()].** or 
1bcb0 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47  evaluating [PRAG
1bcc0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d  MA busy_timeout=
1bcd0 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74  N] will change t
1bce0 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  he.** busy handl
1bcf0 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61  er and thus clea
1bd00 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  r any previously
1bd10 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65   set busy handle
1bd20 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
1bd30 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
1bd40 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
1bd50 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
1bd60 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
1bd70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1bd80 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1bd90 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49  busy handler.  I
1bda0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a  n other words,.*
1bdb0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1bdc0 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  er is not reentr
1bdd0 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ant.  Any such a
1bde0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
1bdf0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
1be00 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
1be10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
1be20 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
1be30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1be40 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
1be50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1be60 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1be70 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1be80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1be90 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
1bea0 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a  e3*,int(*)(void*
1beb0 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f  ,int),void*);../
1bec0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1bed0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
1bee0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
1bef0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1bf00 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1bf10 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1bf20 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1bf30 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1bf40 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1bf50 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1bf60 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1bf70 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1bf80 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1bf90 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1bfa0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1bfb0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1bfc0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1bfd0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1bfe0 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1bff0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1c000 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1c010 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1c020 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1c030 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1c040 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c050 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1c060 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1c070 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1c080 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1c090 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1c0a0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1c0b0 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1c0c0 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1c0d0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1c0e0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1c0f0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1c100 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1c110 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1c120 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1c130 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1c140 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1c150 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1c160 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1c170 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1c180 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1c190 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1c1a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1c1b0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1c1c0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1c1d0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1c1e0 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1c1f0 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69  sy_timeout].*/.i
1c200 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1c210 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1c220 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1c230 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1c240 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1c250 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1c260 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ries.** METHOD: 
1c270 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
1c280 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1c290 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1c2a0 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1c2b0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1c2c0 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1c2d0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1c2e0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1c2f0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1c300 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1c310 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1c320 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1c330 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1c340 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1c350 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1c360 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1c370 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1c380 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1c390 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1c3a0 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1c3b0 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1c3c0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1c3d0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1c3e0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1c3f0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1c400 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1c410 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1c420 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1c430 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1c440 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1c450 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1c460 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1c470 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1c480 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1c490 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1c4a0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1c4b0 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1c4c0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1c4d0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1c4e0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1c4f0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1c500 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1c510 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1c520 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1c530 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1c540 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1c550 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1c560 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1c570 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1c580 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1c590 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1c5a0 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1c5b0 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1c5c0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1c5d0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1c5e0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1c5f0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1c600 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1c610 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1c620 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1c630 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1c640 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1c650 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1c660 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1c670 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1c680 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1c690 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1c6a0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1c6b0 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1c6c0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1c6d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1c6e0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1c6f0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1c700 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1c710 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1c720 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1c730 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1c740 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1c750 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1c760 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1c770 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1c780 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c790 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1c7a0 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1c7b0 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1c7c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1c7d0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1c7e0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1c7f0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1c800 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1c810 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1c820 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1c830 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c840 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1c850 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1c860 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1c870 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1c880 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1c890 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1c8a0 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1c8b0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1c8c0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1c8d0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1c8e0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1c8f0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1c900 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1c910 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c920 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c930 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1c940 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c950 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1c960 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1c970 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1c980 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1c990 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c9a0 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1c9b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1c9c0 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1c9d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1c9e0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1c9f0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1ca00 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1ca10 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1ca20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1ca30 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1ca40 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1ca50 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1ca60 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1ca70 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1ca80 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1ca90 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1caa0 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1cab0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1cac0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1cad0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1cae0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1caf0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1cb00 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1cb10 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1cb20 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1cb30 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1cb40 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1cb50 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1cb60 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1cb70 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1cb80 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1cb90 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1cba0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1cbb0 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1cbc0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1cbd0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1cbe0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1cbf0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1cc00 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1cc10 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1cc20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1cc30 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1cc40 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1cc50 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1cc60 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1cc70 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1cc80 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1cc90 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1cca0 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1ccb0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1ccc0 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1ccd0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1cce0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1ccf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1cd00 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1cd10 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1cd20 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1cd30 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1cd40 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1cd50 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1cd60 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1cd70 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1cd80 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1cd90 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1cda0 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1cdb0 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1cdc0 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1cdd0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1cde0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1cdf0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1ce00 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1ce10 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1ce20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1ce30 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1ce40 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1ce50 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1ce60 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1ce70 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1ce80 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1ce90 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1cea0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1ceb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
1cec0 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
1ced0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1cee0 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
1cef0 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
1cf00 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
1cf10 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
1cf20 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
1cf30 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
1cf40 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
1cf50 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
1cf60 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
1cf70 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1cf80 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
1cf90 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
1cfa0 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
1cfb0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1cfc0 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
1cfd0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1cfe0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
1cff0 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
1d000 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
1d010 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
1d020 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1d030 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
1d040 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d050 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
1d060 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
1d070 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1d080 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
1d090 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
1d0a0 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
1d0b0 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
1d0c0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
1d0d0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1d0e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1d0f0 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f  es understand mo
1d100 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e  st of the common
1d110 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20   K&R formatting 
1d120 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73  options,.** plus
1d130 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1d140 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f   non-standard fo
1d150 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20  rmats, detailed 
1d160 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74  below..** Note t
1d170 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20  hat some of the 
1d180 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72  more obscure for
1d190 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1d1a0 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43  from recent.** C
1d1b0 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 72  -library standar
1d1c0 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66  ds are omitted f
1d1d0 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65  rom this impleme
1d1e0 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ntation..**.** ^
1d1f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
1d200 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
1d210 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
1d220 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
1d230 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
1d240 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
1d250 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
1d260 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
1d270 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1d280 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
1d290 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
1d2a0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
1d2b0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
1d2c0 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
1d2d0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
1d2e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
1d2f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d300 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
1d310 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
1d320 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
1d330 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
1d340 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
1d350 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
1d360 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1d370 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
1d380 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
1d390 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
1d3a0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
1d3b0 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
1d3c0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
1d3d0 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
1d3e0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1d3f0 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
1d400 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
1d410 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1d420 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
1d430 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
1d440 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
1d450 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
1d460 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
1d470 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
1d480 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
1d490 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
1d4a0 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
1d4b0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
1d4c0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
1d4d0 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
1d4e0 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
1d4f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1d500 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
1d510 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
1d520 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1d530 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
1d540 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
1d550 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
1d560 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
1d570 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
1d580 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
1d590 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
1d5a0 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
1d5b0 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
1d5c0 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
1d5d0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
1d5e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1d5f0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1d600 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
1d610 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
1d620 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
1d630 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
1d640 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
1d650 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
1d660 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
1d670 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
1d680 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
1d690 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
1d6a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
1d6b0 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
1d6c0 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
1d6d0 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
1d6e0 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
1d6f0 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
1d700 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
1d710 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
1d720 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
1d730 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
1d740 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
1d750 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
1d760 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
1d770 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1d780 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1d790 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
1d7a0 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
1d7b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
1d7c0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1d7d0 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
1d7e0 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
1d7f0 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
1d800 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
1d810 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
1d820 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
1d830 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
1d840 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
1d850 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
1d860 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
1d870 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
1d880 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
1d890 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61  q", "%Q", "%w" a
1d8a0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1d8b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1d8c0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1d8d0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1d8e0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1d8f0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1d900 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1d910 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1d920 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1d930 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1d940 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1d950 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1d960 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1d970 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1d980 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1d990 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1d9a0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1d9b0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1d9c0 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1d9d0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1d9e0 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1d9f0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1da00 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1da10 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1da20 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1da30 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1da40 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1da50 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1da60 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1da70 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1da80 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1da90 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1daa0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1dab0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1dac0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1dad0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1dae0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1daf0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1db00 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1db10 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1db20 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1db30 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1db40 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1db50 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1db60 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1db70 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1db80 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1db90 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1dba0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1dbb0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1dbc0 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1dbd0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1dbe0 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1dbf0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1dc00 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1dc10 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1dc20 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1dc30 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1dc40 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1dc50 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1dc60 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1dc70 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1dc80 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1dc90 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1dca0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1dcb0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1dcc0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1dcd0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1dce0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1dcf0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1dd00 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1dd10 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1dd20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1dd30 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1dd40 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1dd50 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1dd60 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1dd70 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1dd80 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1dd90 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1dda0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1ddb0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1ddc0 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1ddd0 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1dde0 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1ddf0 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1de00 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1de10 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1de20 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1de30 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1de40 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1de50 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1de60 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1de70 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1de80 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1de90 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1dea0 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1deb0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1dec0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1ded0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1dee0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1def0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1df00 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1df10 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1df20 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1df30 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1df40 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1df50 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1df60 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1df70 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1df80 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1df90 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1dfa0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1dfb0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1dfc0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1dfd0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1dfe0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1dff0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1e000 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1e010 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1e020 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e  e "%w" formattin
1e030 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65  g option is like
1e040 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68 61   "%q" except tha
1e050 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a  t it expects to.
1e060 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  ** be contained 
1e070 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75  within double-qu
1e080 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20  otes instead of 
1e090 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61  single quotes, a
1e0a0 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73  nd it.** escapes
1e0b0 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74   the double-quot
1e0c0 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74  e character inst
1e0d0 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c  ead of the singl
1e0e0 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61  e-quote.** chara
1e0f0 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77  cter.)^  The "%w
1e100 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1e110 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ion is intended 
1e120 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72  for safely inser
1e130 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e  ting.** table an
1e140 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69  d column names i
1e150 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65  nto a constructe
1e160 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  d SQL statement.
1e170 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
1e180 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1e190 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
1e1a0 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
1e1b0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
1e1c0 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
1e1d0 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
1e1e0 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
1e1f0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
1e200 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1e210 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
1e220 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
1e230 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ^.*/.char *sqlit
1e240 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1e250 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
1e260 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1e270 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1e280 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
1e290 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1e2a0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1e2b0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63  t char*, ...);.c
1e2c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
1e2d0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1e2e0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1e2f0 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1e300 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1e310 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1e320 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1e330 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1e340 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1e350 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1e360 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1e370 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1e380 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1e390 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1e3a0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1e3b0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1e3c0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1e3d0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1e3e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1e3f0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1e400 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1e410 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1e420 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1e430 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1e440 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1e450 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1e460 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1e470 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1e480 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1e490 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1e4a0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1e4b0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1e4c0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1e4d0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1e4e0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1e4f0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1e500 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1e510 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1e520 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1e530 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1e540 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1e550 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1e560 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1e570 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1e580 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1e590 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e5a0 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f  3_malloc64(N) ro
1e5b0 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74  utine works just
1e5c0 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33   like.** sqlite3
1e5d0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70  _malloc(N) excep
1e5e0 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75  t that N is an u
1e5f0 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69  nsigned 64-bit i
1e600 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1e610 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32  * of a signed 32
1e620 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  -bit integer..**
1e630 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1e640 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1e650 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1e660 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1e670 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1e680 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1e690 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1e6a0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1e6b0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1e6c0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1e6d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1e6e0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1e6f0 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1e700 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1e710 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1e720 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1e730 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1e740 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1e750 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1e760 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1e770 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1e780 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1e790 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1e7a0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1e7b0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1e7c0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1e7d0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1e7e0 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1e7f0 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1e800 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1e810 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1e820 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1e830 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1e840 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1e850 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1e860 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1e870 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1e880 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1e890 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1e8a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e8b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1e8c0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  lloc()..**.** ^T
1e8d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1e8e0 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  oc(X,N) interfac
1e8f0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1e900 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1e910 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1e920 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61  n X to be at lea
1e930 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  st N bytes..** ^
1e940 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  If the X paramet
1e950 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1e960 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73  alloc(X,N).** is
1e970 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1e980 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1e990 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1e9a0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1e9b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a  ite3_malloc(N)..
1e9c0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72  ** ^If the N par
1e9d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1e9e0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1e9f0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1ea00 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1ea10 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1ea20 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1ea30 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1ea40 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73  3_free(X)..** ^s
1ea50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1ea60 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ,N) returns a po
1ea70 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1ea80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1ea90 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1eaa0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1eab0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
1eac0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76  ent memory is av
1ead0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1eae0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1eaf0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1eb00 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1eb10 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1eb20 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1eb30 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1eb40 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1eb50 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1eb60 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1eb70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1eb80 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1eb90 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1eba0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1ebb0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1ebc0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
1ebd0 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c  d N is positive,
1ebe0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69   then the.** pri
1ebf0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1ec00 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1ec10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1ec20 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e  ealloc64(X,N) in
1ec30 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74  terfaces works t
1ec40 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
1ec50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1ec60 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1ec70 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73   is a 64-bit uns
1ec80 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e  igned integer in
1ec90 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32  stead.** of a 32
1eca0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1ecb0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58  ger..**.** ^If X
1ecc0 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   is a memory all
1ecd0 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73  ocation previous
1ece0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
1ecf0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ed00 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
1ed10 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65  lloc64(), sqlite
1ed20 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20  3_realloc(), or 
1ed30 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1ed40 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  4(), then.** sql
1ed50 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1ed60 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
1ed70 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c  f that memory al
1ed80 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65  location in byte
1ed90 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  s..** ^The value
1eda0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1edb0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69  ite3_msize(X) mi
1edc0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
1edd0 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  an the number.**
1ede0 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73   of bytes reques
1edf0 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61  ted when X was a
1ee00 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58  llocated.  ^If X
1ee10 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1ee20 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  er then.** sqlit
1ee30 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1ee40 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20  rns zero.  If X 
1ee50 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68  points to someth
1ee60 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a  ing that is not.
1ee70 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  ** the beginning
1ee80 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
1ee90 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20  ation, or if it 
1eea0 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d  points to a form
1eeb0 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65  erly.** valid me
1eec0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1eed0 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65  that has now bee
1eee0 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68  n freed, then th
1eef0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
1ef00 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1ef10 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  ) is undefined a
1ef20 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d  nd possibly harm
1ef30 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ful..**.** ^The 
1ef40 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1ef50 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1ef60 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  c(), sqlite3_rea
1ef70 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1ef80 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61  e3_malloc64(), a
1ef90 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1efa0 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77  oc64().** is alw
1efb0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1efc0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1efd0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1efe0 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1eff0 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1f000 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1f010 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1f020 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1f030 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1f040 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1f050 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1f060 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1f070 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1f080 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1f090 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1f0a0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1f0b0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1f0c0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1f0d0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1f0e0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1f0f0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1f100 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1f110 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1f120 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1f130 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1f140 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1f150 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1f160 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1f170 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1f180 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1f190 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1f1a0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1f1b0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1f1c0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1f1d0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1f1e0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1f1f0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1f200 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1f210 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1f220 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1f230 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1f240 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1f250 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1f260 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1f270 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1f280 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1f290 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1f2a0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1f2b0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1f2c0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1f2d0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1f2e0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1f2f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1f300 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1f310 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1f320 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1f330 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1f340 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1f350 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1f360 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1f370 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1f380 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1f390 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1f3a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f3b0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1f3c0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1f3d0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1f3e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1f3f0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1f400 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1f410 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1f420 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1f430 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1f440 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1f450 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1f460 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1f470 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1f480 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
1f490 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1f4a0 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69  loc64(sqlite3_ui
1f4b0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  nt64);.void *sql
1f4c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1f4d0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  d*, int);.void *
1f4e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1f4f0 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  4(void*, sqlite3
1f500 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  _uint64);.void s
1f510 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1f520 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74  *);.sqlite3_uint
1f530 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  64 sqlite3_msize
1f540 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1f550 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1f560 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1f570 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1f580 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1f590 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1f5a0 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1f5b0 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1f5c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1f5d0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1f5e0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1f5f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1f600 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1f610 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1f620 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1f630 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1f640 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1f650 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1f660 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1f670 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1f680 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1f690 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1f6a0 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1f6b0 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1f6c0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1f6d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1f6e0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1f6f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1f700 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1f710 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1f720 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1f730 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1f740 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1f750 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1f760 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1f770 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1f780 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1f790 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1f7a0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1f7b0 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1f7c0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1f7d0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1f7e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1f7f0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1f800 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1f810 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1f820 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1f830 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1f840 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1f850 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1f860 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1f870 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1f880 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1f890 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1f8a0 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1f8b0 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1f8c0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1f8d0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1f8e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1f8f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1f900 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1f910 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1f920 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1f930 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1f940 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1f950 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1f960 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1f970 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1f980 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1f990 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1f9a0 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
1f9b0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1f9c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1f9d0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1f9e0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1f9f0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1fa00 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1fa10 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1fa20 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1fa30 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1fa40 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1fa50 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1fa60 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1fa70 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1fa80 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1fa90 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1faa0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1fab0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1fac0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1fad0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1fae0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1faf0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1fb00 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1fb10 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1fb20 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1fb30 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1fb40 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1fb50 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1fb60 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1fb70 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1fb80 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1fb90 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1fba0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1fbb0 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1fbc0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1fbd0 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  er P..** ^The P 
1fbe0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
1fbf0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1fc00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20  .**.** ^If this 
1fc10 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20  routine has not 
1fc20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  been previously 
1fc30 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65  called or if the
1fc40 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c   previous.** cal
1fc50 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61  l had N less tha
1fc60 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20  n one or a NULL 
1fc70 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74  pointer for P, t
1fc80 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a  hen the PRNG is.
1fc90 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  ** seeded using 
1fca0 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
1fcb0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
1fcc0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1fcd0 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  of.** the defaul
1fce0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1fcf0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74  object..** ^If t
1fd00 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
1fd10 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1fd20 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f   had an N of 1 o
1fd30 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20  r more and a.** 
1fd40 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20  non-NULL P then 
1fd50 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
1fd60 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
1fd70 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
1fd80 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
1fd90 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
1fda0 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
1fdb0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
1fdc0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1fdd0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
1fde0 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
1fdf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1fe00 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
1fe10 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
1fe20 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
1fe30 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1fe40 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
1fe50 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
1fe60 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
1fe70 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1fe80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1fe90 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
1fea0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1feb0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
1fec0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fed0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
1fee0 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
1fef0 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
1ff00 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
1ff10 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1ff20 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
1ff30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ff40 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
1ff50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
1ff60 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1ff70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
1ff80 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
1ff90 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
1ffa0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
1ffb0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
1ffc0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
1ffd0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
1ffe0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
1fff0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20000 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
20010 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
20020 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
20030 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
20040 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20050 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
20060 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
20070 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
20080 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
20090 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
200a0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
200b0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
200c0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
200d0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
200e0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
200f0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
20100 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
20110 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
20120 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
20130 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
20140 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
20150 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20160 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
20170 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
20180 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
20190 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
201a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
201b0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
201c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
201d0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
201e0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
201f0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
20200 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
20210 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
20220 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
20230 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
20240 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
20250 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
20260 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
20270 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
20280 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
20290 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
202a0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
202b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
202c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
202d0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
202e0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
202f0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
20300 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
20310 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
20320 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
20330 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
20340 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
20350 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
20360 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
20370 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20380 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
20390 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
203a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
203b0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
203c0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
203d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
203e0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
203f0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
20400 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
20410 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
20420 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
20430 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
20440 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
20450 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
20460 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
20470 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
20480 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
20490 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
204a0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
204b0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
204c0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
204d0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
204e0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
204f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
20500 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
20510 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
20520 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
20530 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
20540 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
20550 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
20560 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
20570 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
20580 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
20590 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
205a0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
205b0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
205c0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
205d0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
205e0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
205f0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
20600 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
20610 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
20620 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
20630 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
20640 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
20650 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
20660 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
20670 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
20680 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
20690 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
206a0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
206b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
206c0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
206d0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
206e0 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
206f0 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
20700 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
20710 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
20720 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
20730 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
20740 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
20750 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
20760 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20770 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
20780 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
20790 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
207a0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
207b0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
207c0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
207d0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
207e0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
207f0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
20800 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
20810 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
20820 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
20830 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
20840 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
20850 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
20860 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
20870 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
20880 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
20890 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
208a0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
208b0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
208c0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
208d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
208e0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
208f0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
20900 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
20910 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
20920 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
20930 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
20940 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
20950 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
20960 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
20970 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
20980 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
20990 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
209a0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
209b0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
209c0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
209d0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
209e0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
209f0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
20a00 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
20a10 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
20a20 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
20a30 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
20a40 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
20a50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
20a60 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
20a70 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
20a80 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
20a90 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
20aa0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
20ab0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
20ac0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
20ad0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
20ae0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
20af0 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
20b00 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
20b10 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
20b20 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
20b30 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
20b40 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
20b50 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
20b60 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
20b70 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
20b80 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
20b90 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
20ba0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
20bb0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
20bc0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
20bd0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
20be0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
20bf0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
20c00 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
20c10 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
20c20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
20c30 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
20c40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20c50 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
20c60 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
20c70 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
20c80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
20c90 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
20ca0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
20cb0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
20cc0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
20cd0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
20ce0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
20cf0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
20d00 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
20d10 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
20d20 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
20d30 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
20d40 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
20d50 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
20d60 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
20d70 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
20d80 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
20d90 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
20da0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
20db0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
20dc0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20dd0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
20de0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
20df0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
20e00 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
20e10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20e20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
20e30 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
20e40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
20e50 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
20e60 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
20e70 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
20e80 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
20e90 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
20ea0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
20eb0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
20ec0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
20ed0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
20ee0 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
20ef0 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
20f00 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
20f10 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
20f20 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
20f30 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
20f40 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
20f50 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
20f60 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
20f70 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
20f80 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
20f90 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
20fa0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
20fb0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
20fc0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
20fd0 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
20fe0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
20ff0 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
21000 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
21010 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
21020 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
21030 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
21040 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
21050 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
21060 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
21070 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
21080 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
21090 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
210a0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
210b0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
210c0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
210d0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
210e0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
210f0 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
21100 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
21110 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
21120 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
21130 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
21140 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
21150 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65  s a [conflict re
21160 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a  solution mode].*
21170 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  * returned from 
21180 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
21190 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
211a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
211b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
211c0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
211d0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
211e0 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
211f0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
21200 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
21210 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
21220 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
21230 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
21240 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
21250 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
21260 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
21270 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
21280 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
21290 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
212a0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
212b0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
212c0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
212d0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
212e0 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
212f0 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
21300 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
21310 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
21320 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
21330 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
21340 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
21350 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
21360 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
21370 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
21380 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
21390 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
213a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
213b0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
213c0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
213d0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
213e0 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
213f0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
21400 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
21410 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
21420 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
21430 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
21440 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
21450 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
21460 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
21470 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
21480 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
21490 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
214a0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
214b0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
214c0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
214d0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
214e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
214f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
21500 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
21510 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
21520 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
21530 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
21540 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
21550 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21560 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
21570 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
21580 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
21590 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
215a0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
215b0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
215c0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
215d0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
215e0 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
215f0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
21600 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
21610 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21620 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21630 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
21640 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
21650 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
21660 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21670 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
21680 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
21690 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
216a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
216b0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
216c0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
216d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
216e0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
216f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21700 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21710 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
21720 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
21730 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21740 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21750 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21760 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
21770 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21780 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21790 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
217a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
217b0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
217c0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
217d0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
217e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
217f0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
21800 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
21810 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
21820 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21830 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21840 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
21850 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
21860 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
21870 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21880 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21890 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
218a0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
218b0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
218c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
218d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
218e0 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
218f0 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
21900 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21910 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21930 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
21940 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
21950 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
21960 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21970 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21980 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
21990 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
219a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
219b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
219c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
219d0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
219e0 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
219f0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
21a00 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21a10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21a20 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
21a30 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
21a40 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21a50 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21a60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21a70 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
21a80 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
21a90 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
21aa0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21ab0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21ac0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
21ad0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
21ae0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
21af0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21b00 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21b10 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
21b20 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
21b30 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
21b40 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21b50 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
21b60 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
21b70 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
21b80 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21b90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21ba0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
21bb0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
21bc0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21bd0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21be0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21bf0 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
21c00 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
21c10 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
21c20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
21c30 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
21c40 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
21c50 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
21c60 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21c70 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
21c80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21c90 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
21ca0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
21cb0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
21cc0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21cd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21ce0 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
21cf0 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
21d00 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
21d10 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21d20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21d30 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
21d40 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
21d50 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21d60 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
21d70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21d80 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
21d90 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
21da0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
21db0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21dc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21dd0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
21de0 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
21df0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
21e00 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21e10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21e20 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
21e30 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
21e40 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
21e50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21e60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
21e70 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
21e80 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
21e90 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
21ea0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21eb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
21ec0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
21ed0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
21ee0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21ef0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21f00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21f10 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
21f20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
21f30 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
21f40 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
21f50 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21f60 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
21f70 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
21f80 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
21f90 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
21fa0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
21fb0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
21fc0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
21fd0 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
21fe0 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
21ff0 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
22000 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
22010 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
22020 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
22030 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
22040 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
22050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
22060 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
22070 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
22080 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45  SQLITE_RECURSIVE
22090 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20              33  
220a0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
220b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
220c0 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41      */../*.** CA
220d0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
220e0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
220f0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
22100 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
22110 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
22120 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20  are deprecated. 
22130 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
22140 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74  _trace_v2()] int
22150 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61  erface.** instea
22160 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65  d of the routine
22170 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65  s described here
22180 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
22190 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
221a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
221b0 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
221c0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
221d0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
221e0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
221f0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
22200 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
22210 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
22220 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
22230 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
22240 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
22250 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
22260 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
22270 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
22280 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
22290 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
222a0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
222b0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
222c0 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
222d0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
222e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
222f0 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
22300 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
22310 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
22320 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
22330 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
22340 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
22350 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
22360 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
22370 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
22380 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
22390 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
223a0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
223b0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
223c0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
223d0 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  igger.)^.**.** T
223e0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
223f0 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
22400 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
22410 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
22420 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e  limit.** the len
22430 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  gth of [bound pa
22440 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69  rameter] expansi
22450 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74  on in the output
22460 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63   of sqlite3_trac
22470 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e()..**.** ^The 
22480 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
22490 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
224a0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
224b0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
224c0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
224d0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
224e0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
224f0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
22500 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
22510 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
22520 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
22530 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
22540 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
22550 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
22560 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
22570 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
22580 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
22590 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
225a0 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
225b0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
225c0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
225d0 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
225e0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
225f0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
22600 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
22610 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
22620 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
22630 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
22640 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
22650 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
22660 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
22670 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
22680 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
22690 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
226a0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
226b0 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
226c0 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
226d0 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
226e0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
226f0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
22700 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
22710 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
22720 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
22730 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a  trace(sqlite3*,.
22740 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29     void(*xTrace)
22750 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
22760 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
22770 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
22780 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
22790 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
227a0 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
227b0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
227c0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
227d0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
227e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
227f0 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f  L Trace Event Co
22800 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
22810 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a   SQLITE_TRACE.**
22820 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
22830 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61  nts identify cla
22840 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74  sses of events t
22850 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74  hat can be monit
22860 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ored.** using th
22870 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  e [sqlite3_trace
22880 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c  _v2()] tracing l
22890 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72 64  ogic.  The third
228a0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
228b0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
228c0 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64  2()] is an OR-ed
228d0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20   combination of 
228e0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a  one or more of.*
228f0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
22900 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65  constants.  ^The
22910 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
22920 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
22930 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20  lback.** is one 
22940 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
22950 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
22960 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f  * New tracing co
22970 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61  nstants may be a
22980 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
22990 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  eleases..**.** ^
229a0 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  A trace callback
229b0 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65   has four argume
229c0 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54  nts: xCallback(T
229d0 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65  ,C,P,X)..** ^The
229e0 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f   T argument is o
229f0 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ne of the intege
22a00 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f  r type codes abo
22a10 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72  ve..** ^The C ar
22a20 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79  gument is a copy
22a30 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20   of the context 
22a40 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
22a50 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  n as the.** four
22a60 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
22a70 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
22a80 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e  ()]..** The P an
22a90 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72  d X arguments ar
22aa0 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65  e pointers whose
22ab0 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64   meanings depend
22ac0 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c   on T..**.** <dl
22ad0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  >.** [[SQLITE_TR
22ae0 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53  ACE_STMT]] <dt>S
22af0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
22b00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
22b10 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54   SQLITE_TRACE_ST
22b20 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  MT callback is i
22b30 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72  nvoked when a pr
22b40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22b50 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73  .** first begins
22b60 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73   running and pos
22b70 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74  sibly at other t
22b80 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a  imes during the.
22b90 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  ** execution of 
22ba0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
22bb0 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20  tement, such as 
22bc0 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66 20  at the start of 
22bd0 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20  each.** trigger 
22be0 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65  subprogram. ^The
22bf0 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
22c00 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
22c10 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
22c20 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20  tement]. ^The X 
22c30 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
22c40 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
22c50 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  g which.** is th
22c60 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c  e unexpanded SQL
22c70 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72 65   text of the pre
22c80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
22c90 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e  or an SQL commen
22ca0 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  t .** that indic
22cb0 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74  ates the invocat
22cc0 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72  ion of a trigger
22cd0 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  .  ^The callback
22ce0 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20   can compute.** 
22cf0 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74 68  the same text th
22d00 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65  at would have be
22d10 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  en returned by t
22d20 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
22d30 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69  e3_trace()].** i
22d40 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69 6e  nterface by usin
22d50 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74  g the X argument
22d60 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77   when X begins w
22d70 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76  ith "--" and inv
22d80 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  oking.** [sqlite
22d90 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
22da0 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  )] otherwise..**
22db0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
22dc0 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74  CE_PROFILE]] <dt
22dd0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52  >SQLITE_TRACE_PR
22de0 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OFILE</dt>.** <d
22df0 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
22e00 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62  CE_PROFILE callb
22e10 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70  ack provides app
22e20 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73  roximately the s
22e30 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ame.** informati
22e40 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64 65  on as is provide
22e50 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
22e60 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c  3_profile()] cal
22e70 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50  lback..** ^The P
22e80 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
22e90 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70  ointer to the [p
22ea0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22eb0 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20  t] and the.** X 
22ec0 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
22ed0 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65  to a 64-bit inte
22ee0 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68 65  ger which is the
22ef0 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a   estimated of.**
22f00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e   the number of n
22f10 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74  anosecond that t
22f20 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
22f30 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
22f40 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54  n..** ^The SQLIT
22f50 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
22f60 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
22f70 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74 61  ked when the sta
22f80 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
22f90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
22fa0 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e  TRACE_ROW]] <dt>
22fb0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
22fc0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
22fd0 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f   SQLITE_TRACE_RO
22fe0 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  W callback is in
22ff0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
23000 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
23010 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73  tement generates
23020 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
23030 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54   result.  .** ^T
23040 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
23050 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23060 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
23070 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a  ement] and the.*
23080 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20  * X argument is 
23090 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  unused..**.** [[
230a0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
230b0 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  SE]] <dt>SQLITE_
230c0 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e  TRACE_CLOSE</dt>
230d0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
230e0 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63  TE_TRACE_CLOSE c
230f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
23100 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  ed when a databa
23110 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
23120 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65   closes..** ^The
23130 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
23140 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
23150 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23160 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  tion] object.** 
23170 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d 65  and the X argume
23180 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
23190 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
231a0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  e SQLITE_TRACE_S
231b0 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a 23  TMT       0x01.#
231c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
231d0 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30  ACE_PROFILE    0
231e0 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x02.#define SQLI
231f0 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20  TE_TRACE_ROW    
23200 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65      0x04.#define
23210 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c   SQLITE_TRACE_CL
23220 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f  OSE      0x08../
23230 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
23240 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a  QL Trace Hook.**
23250 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
23260 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23270 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d  te3_trace_v2(D,M
23280 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
23290 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61 63  registers a trac
232a0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
232b0 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74  nction X against
232c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
232d0 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20  ction] D, using 
232e0 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a  property mask M.
232f0 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70  ** and context p
23300 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74  ointer P.  ^If t
23310 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73  he X callback is
23320 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74  .** NULL or if t
23330 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72  he M mask is zer
23340 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20  o, then tracing 
23350 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68  is disabled.  Th
23360 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20  e.** M argument 
23370 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69  should be the bi
23380 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62  twise OR-ed comb
23390 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65  ination of.** ze
233a0 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49  ro or more [SQLI
233b0 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61  TE_TRACE] consta
233c0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  nts..**.** ^Each
233d0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
233e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
233f0 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  or sqlite3_trace
23400 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73 20  _v2() overrides 
23410 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e  .** (cancels) an
23420 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f  y prior calls to
23430 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
23440 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
23450 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e_v2()..**.** ^T
23460 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73  he X callback is
23470 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
23480 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65  r any of the eve
23490 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20 62  nts identified b
234a0 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63  y .** mask M occ
234b0 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65  ur.  ^The intege
234c0 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  r return value f
234d0 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  rom the callback
234e0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a   is currently.**
234f0 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68   ignored, though
23500 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65   this may change
23510 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
23520 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a  ses.  Callback.*
23530 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
23540 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  s should return 
23550 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66  zero to ensure f
23560 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c  uture compatibil
23570 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72  ity..**.** ^A tr
23580 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
23590 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75  invoked with fou
235a0 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c  r arguments: cal
235b0 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a  lback(T,C,P,X)..
235c0 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65  ** ^The T argume
235d0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  nt is one of the
235e0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a   [SQLITE_TRACE].
235f0 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20  ** constants to 
23600 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68 65  indicate why the
23610 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e   callback was in
23620 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43  voked..** ^The C
23630 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63   argument is a c
23640 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
23650 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54  xt pointer..** T
23660 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d  he P and X argum
23670 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72  ents are pointer
23680 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73  s whose meanings
23690 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a   depend on T..**
236a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
236b0 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72  trace_v2() inter
236c0 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
236d0 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20   to replace the 
236e0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
236f0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72  aces [sqlite3_tr
23700 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ace()] and [sqli
23710 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20  te3_profile()], 
23720 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a  both of which.**
23730 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
23740 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23750 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69  trace_v2(.  sqli
23760 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64  te3*,.  unsigned
23770 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78   uMask,.  int(*x
23780 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e  Callback)(unsign
23790 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76  ed,void*,void*,v
237a0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  oid*),.  void *p
237b0 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Ctx.);../*.** CA
237c0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
237d0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
237e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
237f0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
23800 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
23810 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
23820 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
23830 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
23840 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
23850 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
23860 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
23870 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
23880 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
23890 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
238a0 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
238b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
238c0 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
238d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
238e0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
238f0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
23900 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
23910 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
23920 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
23930 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
23940 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
23950 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
23960 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
23970 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
23980 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
23990 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
239a0 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
239b0 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
239c0 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
239d0 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
239e0 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
239f0 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
23a00 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
23a10 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
23a20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
23a30 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
23a40 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
23a50 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
23a60 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
23a70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
23a80 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
23a90 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
23aa0 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
23ab0 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
23ac0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23ad0 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
23ae0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23af0 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
23b00 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
23b10 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
23b20 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
23b30 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
23b40 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
23b50 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
23b60 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
23b70 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
23b80 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
23b90 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
23ba0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
23bb0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
23bc0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
23bd0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
23be0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
23bf0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
23c00 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
23c10 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
23c20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
23c30 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
23c40 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
23c50 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
23c60 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
23c70 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
23c80 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
23c90 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
23ca0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
23cb0 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
23cc0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
23cd0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
23ce0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23cf0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
23d00 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
23d10 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
23d20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
23d30 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
23d40 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
23d50 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
23d60 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
23d70 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
23d80 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
23d90 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
23da0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
23db0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
23dc0 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
23dd0 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43   Connection.** C
23de0 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  ONSTRUCTOR: sqli
23df0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
23e00 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
23e10 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
23e20 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
23e30 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
23e40 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
23e50 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
23e60 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
23e70 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
23e80 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
23e90 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
23ea0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
23eb0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
23ec0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
23ed0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
23ee0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
23ef0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23f00 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
23f10 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
23f20 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
23f30 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
23f40 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
23f50 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
23f60 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
23f70 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
23f80 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
23f90 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
23fa0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
23fb0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
23fc0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
23fd0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
23fe0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
23ff0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
24000 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
24010 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
24020 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
24030 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
24040 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
24050 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
24060 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
24070 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
24080 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
24090 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
240a0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
240b0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
240c0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
240d0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
240e0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
240f0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
24100 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
24110 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
24120 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
24130 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24140 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
24150 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
24160 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54  oding will be UT
24170 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65  F-8 for database
24180 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
24190 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
241a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
241b0 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65  n_v2().  ^The de
241c0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
241d0 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20  or databases.** 
241e0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71  created using sq
241f0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77  lite3_open16() w
24200 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e  ill be UTF-16 in
24210 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
24220 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68   order..**.** Wh
24230 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
24240 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
24250 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
24260 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
24270 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
24280 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24290 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
242a0 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
242b0 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
242c0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
242d0 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
242e0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
242f0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
24300 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24310 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
24320 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
24330 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
24340 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
24350 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
24360 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
24370 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
24380 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
24390 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
243a0 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
243b0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
243c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
243d0 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
243e0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
243f0 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
24400 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
24410 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
24420 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
24430 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
24440 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
24450 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
24460 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
24470 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24480 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
24490 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
244a0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
244b0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
244c0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
244d0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
244e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
244f0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
24500 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
24510 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
24520 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
24530 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
24540 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
24550 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
24560 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
24570 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
24580 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
24590 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
245a0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
245b0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
245c0 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
245d0 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
245e0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
245f0 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
24600 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
24610 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
24620 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
24630 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
24640 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
24650 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
24660 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
24670 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
24680 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
24690 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
246a0 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
246b0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
246c0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
246d0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
246e0 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
246f0 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
24700 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
24710 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
24720 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
24730 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
24740 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24750 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
24760 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
24770 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
24780 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
24790 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
247a0 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
247b0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
247c0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
247d0 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
247e0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
247f0 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
24800 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
24810 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
24820 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
24830 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
24840 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
24850 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
24860 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
24870 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
24880 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24890 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
248a0 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
248b0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
248c0 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
248d0 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
248e0 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
248f0 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
24900 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
24910 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
24920 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
24930 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
24940 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
24950 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24960 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
24970 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
24980 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
24990 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
249a0 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
249b0 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
249c0 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
249d0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
249e0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
249f0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
24a00 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
24a10 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24a20 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
24a30 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
24a40 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
24a50 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
24a60 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
24a70 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
24a80 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
24a90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
24aa0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
24ab0 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
24ac0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
24ad0 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
24ae0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
24af0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
24b00 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
24b10 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
24b20 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
24b30 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
24b40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
24b50 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
24b60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24b70 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
24b80 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
24b90 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
24ba0 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
24bb0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
24bc0 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
24bd0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
24be0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
24bf0 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
24c00 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
24c10 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
24c20 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
24c30 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
24c40 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
24c50 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
24c60 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
24c70 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
24c80 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
24c90 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
24ca0 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
24cb0 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
24cc0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
24cd0 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
24ce0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
24cf0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
24d00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24d10 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
24d20 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
24d30 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
24d40 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
24d50 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
24d60 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
24d70 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
24d80 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
24d90 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
24da0 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
24db0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
24dc0 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
24dd0 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
24de0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
24df0 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
24e00 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
24e10 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
24e20 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
24e30 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
24e40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
24e50 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
24e60 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
24e70 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
24e80 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
24e90 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
24ea0 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
24eb0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
24ec0 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
24ed0 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
24ee0 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
24ef0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24f00 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
24f10 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
24f20 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
24f30 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
24f40 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
24f50 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
24f60 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
24f70 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
24f80 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
24f90 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
24fa0 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
24fb0 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
24fc0 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
24fd0 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
24fe0 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
24ff0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
25000 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
25010 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
25020 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
25030 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
25040 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
25050 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
25060 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
25070 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
25080 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
25090 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
250a0 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
250b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
250c0 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
250d0 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
250e0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
250f0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
25100 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
25110 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
25120 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
25130 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
25140 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
25150 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
25160 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
25170 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
25180 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
25190 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
251a0 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
251b0 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
251c0 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
251d0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
251e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
251f0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
25200 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
25210 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
25220 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
25230 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
25240 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
25250 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
25260 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
25270 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
25280 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
25290 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
252a0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
252b0 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
252c0 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
252d0 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
252e0 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
252f0 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
25300 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
25310 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
25320 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
25330 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
25340 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
25350 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
25360 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
25370 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
25380 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
25390 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
253a0 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
253b0 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
253c0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
253d0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
253e0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
253f0 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
25400 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
25410 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
25420 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
25430 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
25440 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
25450 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
25460 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
25470 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
25480 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
25490 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
254a0 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
254b0 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
254c0 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
254d0 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
254e0 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
254f0 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
25500 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
25510 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
25520 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
25530 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
25540 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
25550 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
25560 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
25570 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
25580 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
25590 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
255a0 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
255b0 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
255c0 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
255d0 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
255e0 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
255f0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
25600 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
25610 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
25620 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
25630 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
25640 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
25650 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
25660 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
25670 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
25680 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
25690 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
256a0 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
256b0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
256c0 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
256d0 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
256e0 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
256f0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
25700 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
25710 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
25720 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
25730 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
25740 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
25750 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
25760 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
25770 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
25780 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
25790 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
257a0 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
257b0 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
257c0 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
257d0 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
257e0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
257f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
25800 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
25810 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
25820 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
25830 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
25840 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
25850 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
25860 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
25870 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
25880 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
25890 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
258a0 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
258b0 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
258c0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
258d0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
258e0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
258f0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
25900 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
25910 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
25920 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
25930 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
25940 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
25950 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
25960 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
25970 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25980 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
25990 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
259a0 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
259b0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
259c0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
259d0 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
259e0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
259f0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
25a00 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
25a10 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
25a20 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
25a30 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
25a40 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
25a50 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
25a60 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
25a70 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
25a80 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
25a90 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
25aa0 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
25ab0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
25ac0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
25ad0 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
25ae0 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
25af0 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
25b00 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
25b10 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
25b20 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
25b30 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
25b40 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
25b50 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
25b60 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
25b70 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
25b80 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
25b90 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
25ba0 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
25bb0 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
25bc0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
25bd0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
25be0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
25bf0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
25c00 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
25c10 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
25c20 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
25c30 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
25c40 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
25c50 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
25c60 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
25c70 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
25c80 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
25c90 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
25ca0 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
25cb0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
25cc0 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
25cd0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
25ce0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
25cf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
25d00 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
25d10 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
25d20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
25d30 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
25d40 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
25d50 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
25d60 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
25d70 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
25d80 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
25d90 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
25da0 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
25db0 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
25dc0 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
25dd0 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
25de0 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
25df0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
25e00 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
25e10 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
25e20 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
25e30 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
25e40 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
25e50 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
25e60 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
25e70 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
25e80 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
25e90 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
25ea0 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
25eb0 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
25ec0 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
25ed0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
25ee0 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
25ef0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
25f00 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
25f10 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
25f20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
25f30 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
25f40 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
25f50 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
25f60 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
25f70 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
25f80 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
25f90 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
25fa0 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
25fb0 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
25fc0 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
25fd0 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
25fe0 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
25ff0 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
26000 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
26010 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
26020 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
26030 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
26040 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
26050 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
26060 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
26070 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
26080 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
26090 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
260a0 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
260b0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
260c0 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
260d0 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
260e0 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
260f0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
26100 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
26110 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
26120 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
26130 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
26140 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
26150 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
26160 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
26170 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
26180 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
26190 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
261a0 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
261b0 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
261c0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
261d0 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
261e0 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
261f0 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
26200 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
26210 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
26220 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
26230 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
26240 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
26250 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
26260 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
26270 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
26280 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
26290 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
262a0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
262b0 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
262c0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
262d0 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
262e0 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
262f0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
26300 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
26310 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
26320 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
26330 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
26340 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
26350 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
26360 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
26370 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
26380 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
26390 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
263a0 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
263b0 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
263c0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
263d0 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
263e0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
263f0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
26400 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
26410 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
26420 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
26430 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
26440 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
26450 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
26460 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
26470 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
26480 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
26490 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
264a0 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
264b0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
264c0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
264d0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
264e0 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
264f0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
26500 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26510 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
26520 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
26530 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
26540 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
26550 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
26560 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26570 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
26580 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
26590 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
265a0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
265b0 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
265c0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
265d0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
265e0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
265f0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
26600 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
26610 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
26620 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
26630 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
26640 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
26650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
26660 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
26670 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
26680 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
26690 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
266a0 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
266b0 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
266c0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
266d0 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
266e0 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
266f0 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
26700 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
26710 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
26720 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
26730 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
26740 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
26750 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
26760 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
26770 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
26780 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
26790 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
267a0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
267b0 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
267c0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
267d0 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
267e0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
267f0 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
26800 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
26810 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
26820 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
26830 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
26840 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
26850 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
26860 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
26870 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
26880 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
26890 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
268a0 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
268b0 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
268c0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
268d0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
268e0 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
268f0 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
26900 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
26910 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
26920 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
26930 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
26940 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
26950 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26960 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
26970 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
26980 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
26990 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
269a0 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
269b0 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
269c0 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
269d0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
269e0 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
269f0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
26a00 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
26a10 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
26a20 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
26a30 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
26a40 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
26a50 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26a60 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
26a70 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
26a80 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
26a90 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
26aa0 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
26ab0 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
26ac0 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
26ad0 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
26ae0 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
26af0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
26b00 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
26b10 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
26b20 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
26b30 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
26b40 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
26b50 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26b60 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
26b70 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
26b80 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
26b90 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
26ba0 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
26bb0 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
26bc0 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
26bd0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
26be0 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
26bf0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
26c00 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
26c10 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
26c20 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
26c30 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
26c40 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
26c50 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
26c60 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
26c70 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
26c80 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
26c90 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
26ca0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
26cb0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
26cc0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
26cd0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
26ce0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
26cf0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
26d00 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
26d10 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
26d20 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
26d30 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
26d40 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
26d50 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
26d60 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
26d70 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
26d80 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
26d90 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
26da0 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
26db0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
26dc0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26dd0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
26de0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
26df0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
26e00 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
26e10 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
26e20 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
26e30 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
26e40 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
26e50 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
26e60 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
26e70 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
26e80 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26e90 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
26ea0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
26eb0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
26ec0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
26ed0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
26ee0 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
26ef0 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
26f00 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
26f10 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
26f20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
26f30 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
26f40 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
26f50 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
26f60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26f70 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
26f80 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
26f90 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26fa0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
26fb0 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
26fc0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
26fd0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
26fe0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
26ff0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
27000 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
27010 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
27020 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
27030 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
27040 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
27050 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
27060 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
27070 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
27080 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
27090 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
270a0 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
270b0 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
270c0 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
270d0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
270e0 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
270f0 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
27100 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
27110 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
27120 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
27130 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
27140 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
27150 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
27160 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
27170 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
27180 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
27190 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
271a0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
271b0 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
271c0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
271d0 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
271e0 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
271f0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
27200 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
27210 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
27220 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
27230 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
27240 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
27250 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
27260 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
27270 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
27280 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
27290 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
272a0 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
272b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
272c0 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
272d0 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
272e0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
272f0 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
27300 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
27310 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
27320 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
27330 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
27340 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
27350 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
27360 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
27370 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
27380 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27390 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
273a0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
273b0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
273c0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
273d0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
273e0 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
273f0 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
27400 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
27410 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
27420 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
27430 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
27440 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
27450 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
27460 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
27470 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
27480 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
27490 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
274a0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
274b0 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
274c0 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
274d0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
274e0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
274f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
27500 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
27510 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
27520 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
27530 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
27540 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
27550 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
27560 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
27570 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
27580 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
27590 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
275a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
275b0 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
275c0 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
275d0 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
275e0 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
275f0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
27600 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
27610 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
27620 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27630 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
27640 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
27650 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
27660 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
27670 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
27680 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
27690 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
276a0 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
276b0 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
276c0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
276d0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
276e0 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
276f0 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
27700 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
27710 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
27720 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
27730 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27740 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
27750 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
27760 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27770 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
27780 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
27790 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
277a0 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
277b0 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
277c0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
277d0 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
277e0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
277f0 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
27800 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
27810 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
27820 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
27830 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
27840 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e  esirable..*/.con
27850 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27860 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
27870 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
27880 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
27890 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
278a0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
278b0 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
278c0 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
278d0 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
278e0 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
278f0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
27900 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
27910 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
27920 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
27930 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
27940 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
27950 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
27960 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
27970 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
27980 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74  ost recent sqlit
27990 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
279a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
279b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
279c0 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64  ection] D failed
279d0 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
279e0 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e  e3_errcode(D) in
279f0 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
27a00 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
27a10 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
27a20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
27a30 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a   code] for that.
27a40 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20  ** API call..** 
27a50 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
27a60 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20  nt API call was 
27a70 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74  successful,.** t
27a80 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
27a90 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
27aa0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
27ab0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68  ndefined..** ^Th
27ac0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
27ad0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
27ae0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
27af0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
27b00 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
27b10 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
27b20 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27b30 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
27b40 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27b50 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
27b60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
27b70 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
27b80 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
27b90 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
27ba0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
27bb0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
27bc0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
27bd0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
27be0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
27bf0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
27c00 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
27c10 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
27c20 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
27c30 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
27c40 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
27c50 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
27c60 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
27c70 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
27c80 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
27c90 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
27ca0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
27cb0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
27cc0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
27cd0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
27ce0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
27cf0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
27d00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27d10 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
27d20 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
27d30 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
27d40 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
27d50 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
27d60 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
27d70 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
27d80 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
27d90 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
27da0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
27db0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
27dc0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
27dd0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
27de0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
27df0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
27e00 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
27e10 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
27e20 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
27e30 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
27e40 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
27e50 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
27e60 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
27e70 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
27e80 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
27e90 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
27ea0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
27eb0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
27ec0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
27ed0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
27ee0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
27ef0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
27f00 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
27f10 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
27f20 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
27f30 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
27f40 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
27f50 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
27f60 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
27f70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
27f80 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
27f90 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
27fa0 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
27fb0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
27fc0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
27fd0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
27fe0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
27ff0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
28000 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
28010 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
28020 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
28030 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
28040 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
28050 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
28060 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
28070 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
28080 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
28090 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
280a0 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
280b0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
280c0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
280d0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
280e0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
280f0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
28100 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
28110 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28120 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
28130 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
28140 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
28150 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
28160 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28170 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
28180 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
28190 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
281a0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
281b0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
281c0 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
281d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
281e0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
281f0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
28200 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
28210 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
28220 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28230 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
28240 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
28250 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
28260 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
28270 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61  ement that.** ha
28280 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20  s been compiled 
28290 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d  into binary form
282a0 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f   and is ready to
282b0 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a   be evaluated..*
282c0 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61  *.** Think of ea
282d0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
282e0 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63   as a separate c
282f0 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e  omputer program.
28300 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61    The.** origina
28310 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f  l SQL text is so
28320 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72  urce code.  A pr
28330 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28340 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74   object .** is t
28350 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65  he compiled obje
28360 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51  ct code.  All SQ
28370 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  L must be conver
28380 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72  ted into a.** pr
28390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
283a0 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62   before it can b
283b0 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  e run..**.** The
283c0 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61   life-cycle of a
283d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
283e0 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c  ent object usual
283f0 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69  ly goes like thi
28400 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
28410 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
28420 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28430 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  ent object using
28440 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28450 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e  e_v2()]..** <li>
28460 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
28470 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69  [parameters] usi
28480 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
28490 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
284a0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
284b0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
284c0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
284d0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
284e0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
284f0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
28500 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28510 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
28520 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
28530 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
28540 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
28550 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
28560 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
28570 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
28580 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
28590 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
285a0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65  ** </ol>.*/.type
285b0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
285c0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
285d0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
285e0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
285f0 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44  Limits.** METHOD
28600 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
28610 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
28620 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
28630 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
28640 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
28650 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
28660 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
28670 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
28680 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
28690 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
286a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
286b0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
286c0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
286d0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
286e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
286f0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
28700 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
28710 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
28720 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
28730 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
28740 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
28750 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
28760 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
28770 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
28780 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
28790 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
287a0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
287b0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
287c0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
287d0 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
287e0 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
287f0 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
28800 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
28810 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
28820 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
28830 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
28840 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
28850 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
28860 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
28870 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
28880 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
28890 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
288a0 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
288b0 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
288c0 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
288d0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
288e0 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
288f0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
28900 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
28910 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
28920 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
28930 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
28940 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
28950 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
28960 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
28970 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
28980 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
28990 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
289a0 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
289b0 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
289c0 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
289d0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
289e0 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
289f0 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
28a00 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
28a10 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
28a20 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
28a30 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
28a40 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
28a50 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
28a60 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
28a70 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
28a80 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
28a90 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
28aa0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
28ab0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
28ac0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
28ad0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
28ae0 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
28af0 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
28b00 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
28b10 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
28b20 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
28b30 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
28b40 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
28b50 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
28b60 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
28b70 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
28b80 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
28b90 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
28ba0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
28bb0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
28bc0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
28bd0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
28be0 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
28bf0 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
28c00 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
28c10 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
28c20 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
28c30 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
28c40 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
28c50 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
28c60 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
28c70 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
28c80 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
28c90 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
28ca0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
28cb0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
28cc0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
28cd0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
28ce0 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
28cf0 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
28d00 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
28d10 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
28d20 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
28d30 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
28d40 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
28d50 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
28d60 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
28d70 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
28d80 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
28d90 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
28da0 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
28db0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
28dc0 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
28dd0 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
28de0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
28df0 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
28e00 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
28e10 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
28e20 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
28e30 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
28e40 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
28e50 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
28e60 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
28e70 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
28e80 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
28e90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
28ea0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
28eb0 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
28ec0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
28ed0 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
28ee0 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
28ef0 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
28f00 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
28f10 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
28f20 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
28f30 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
28f40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28f50 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
28f60 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
28f70 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
28f80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
28f90 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
28fa0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
28fb0 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
28fc0 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
28fd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
28fe0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
28ff0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
29000 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
29010 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
29020 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
29030 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
29040 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
29050 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29060 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
29070 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
29080 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
29090 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
290a0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
290b0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
290c0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
290d0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
290e0 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
290f0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29100 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
29110 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
29120 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
29130 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
29140 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
29150 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
29160 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
29170 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
29180 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
29190 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
291a0 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
291b0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
291c0 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
291d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
291e0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
291f0 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
29200 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
29210 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
29220 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29230 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
29240 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
29250 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
29260 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
29270 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
29280 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
29290 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
292a0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
292b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
292c0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
292d0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
292e0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
292f0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
29300 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
29310 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
29320 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
29330 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
29340 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
29350 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
29360 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
29370 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
29380 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29390 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
293a0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
293b0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
293c0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
293d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
293e0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
293f0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
29400 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
29410 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29420 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
29430 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29440 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
29450 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29460 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
29470 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
29480 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
29490 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
294a0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
294b0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
294c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
294d0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
294e0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
294f0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
29500 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
29510 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
29520 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
29530 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
29540 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
29550 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29560 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
29570 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
29580 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
29590 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
295a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
295b0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
295c0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
295d0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
295e0 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
295f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
29600 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
29610 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
29620 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
29630 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29640 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
29650 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
29660 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
29670 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29680 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
29690 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
296a0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
296b0 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
296c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
296d0 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
296e0 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
296f0 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
29700 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29710 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
29720 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
29730 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
29740 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
29750 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29760 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
29770 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
29780 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
29790 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
297a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
297b0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
297c0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
297d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
297e0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
297f0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
29800 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
29810 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
29820 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
29830 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
29840 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
29850 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
29860 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
29870 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
29880 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
29890 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
298a0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
298b0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
298c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
298d0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
298e0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
298f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29900 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
29910 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
29920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29930 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
29940 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
29950 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29960 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
29970 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
29980 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29990 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
299a0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
299b0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
299c0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
299d0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
299e0 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
299f0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
29a00 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
29a10 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
29a20 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
29a30 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
29a40 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
29a50 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
29a60 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
29a70 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
29a80 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
29a90 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
29aa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
29ab0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
29ac0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
29ad0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
29ae0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
29af0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
29b00 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
29b10 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
29b20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29b30 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
29b40 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
29b50 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
29b60 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
29b70 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
29b80 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
29b90 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
29ba0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
29bb0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
29bc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
29bd0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
29be0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
29bf0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
29c00 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
29c10 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
29c20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
29c30 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
29c40 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
29c50 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
29c60 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
29c70 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
29c80 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
29c90 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
29ca0 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
29cb0 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
29cc0 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
29cd0 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
29ce0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
29cf0 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
29d00 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
29d10 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
29d20 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
29d30 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
29d40 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
29d50 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
29d60 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
29d70 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
29d80 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
29d90 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
29da0 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
29db0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
29dc0 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
29dd0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
29de0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
29df0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
29e00 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
29e10 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
29e20 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
29e30 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
29e40 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
29e50 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
29e60 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
29e70 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
29e80 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
29e90 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
29ea0 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
29eb0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
29ec0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
29ed0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
29ee0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
29ef0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
29f00 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
29f10 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
29f20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
29f30 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
29f40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29f50 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
29f60 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
29f70 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
29f80 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
29f90 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
29fa0 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
29fb0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
29fc0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
29fd0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
29fe0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
29ff0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
2a000 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
2a010 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
2a020 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
2a030 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
2a040 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
2a050 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
2a060 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
2a070 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
2a080 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2a090 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
2a0a0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2a0b0 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
2a0c0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
2a0d0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
2a0e0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
2a0f0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
2a100 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
2a110 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2a120 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
2a130 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2a140 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2a150 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
2a160 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
2a170 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a180 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
2a190 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
2a1a0 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
2a1b0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
2a1c0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
2a1d0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
2a1e0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
2a1f0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
2a200 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
2a210 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
2a220 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
2a230 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
2a240 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a250 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
2a260 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
2a270 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
2a280 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
2a290 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
2a2a0 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
2a2b0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
2a2c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
2a2d0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
2a2e0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
2a2f0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
2a300 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
2a310 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
2a320 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
2a330 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
2a340 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
2a350 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
2a360 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
2a370 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
2a380 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
2a390 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2a3a0 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
2a3b0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
2a3c0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
2a3d0 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
2a3e0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
2a3f0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
2a400 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
2a410 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
2a420 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
2a430 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
2a440 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
2a450 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
2a460 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
2a470 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
2a480 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
2a490 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
2a4a0 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
2a4b0 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
2a4c0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
2a4d0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
2a4e0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
2a4f0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2a500 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
2a510 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
2a520 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
2a530 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
2a540 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a550 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
2a560 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
2a570 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
2a580 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
2a590 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
2a5a0 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
2a5b0 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
2a5c0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
2a5d0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
2a5e0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
2a5f0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
2a600 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
2a610 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
2a620 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2a630 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
2a640 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
2a650 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
2a660 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
2a670 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
2a680 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
2a690 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2a6a0 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
2a6b0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
2a6c0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
2a6d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
2a6e0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
2a6f0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
2a700 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
2a710 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
2a720 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
2a730 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
2a740 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
2a750 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
2a760 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
2a770 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
2a780 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
2a790 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
2a7a0 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
2a7b0 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
2a7c0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
2a7d0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
2a7e0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
2a7f0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2a800 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
2a810 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
2a820 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
2a830 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
2a840 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
2a850 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2a860 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
2a870 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
2a880 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
2a890 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
2a8a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2a8b0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
2a8c0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
2a8d0 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
2a8e0 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
2a8f0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2a900 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2a910 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a920 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2a930 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2a940 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2a950 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2a960 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2a970 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2a980 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2a990 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2a9a0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2a9b0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2a9c0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2a9d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2a9e0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2a9f0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2aa00 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2aa10 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2aa20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2aa30 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2aa40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2aa50 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2aa60 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2aa70 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2aa80 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2aa90 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2aaa0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2aab0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2aac0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2aad0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2aae0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2aaf0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2ab00 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2ab10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2ab20 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2ab30 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2ab40 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2ab50 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2ab60 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2ab70 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
2ab80 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2ab90 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2aba0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2abb0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2abc0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2abd0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2abe0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2abf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2ac00 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2ac10 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2ac20 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2ac30 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2ac40 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2ac50 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2ac60 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2ac70 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2ac80 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2ac90 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2aca0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2acb0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
2acc0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2acd0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2ace0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2acf0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2ad00 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2ad10 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2ad20 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2ad30 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2ad40 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2ad50 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2ad60 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2ad70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2ad80 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2ad90 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2ada0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2adb0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2adc0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2add0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2ade0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
2adf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2ae00 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
2ae10 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
2ae20 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ae30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ae40 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  e3_sql(P) interf
2ae50 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2ae60 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20  inter to a copy 
2ae70 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20  of the UTF-8.** 
2ae80 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
2ae90 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65   create [prepare
2aea0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69  d statement] P i
2aeb0 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74  f P was.** creat
2aec0 65 64 20 62 79 20 65 69 74 68 65 72 20 5b 73 71  ed by either [sq
2aed0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2aee0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2aef0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2af00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2af10 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2af20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2af30 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2af40 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  a UTF-8.** strin
2af50 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
2af60 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65   SQL text of pre
2af70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2af80 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64  P with.** [bound
2af90 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70   parameters] exp
2afa0 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  anded..**.** ^(F
2afb0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2afc0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2afd0 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 75  ent is created u
2afe0 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20  sing the SQL.** 
2aff0 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 62  text "SELECT $ab
2b000 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70  c,:xyz" and if p
2b010 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 73  arameter $abc is
2b020 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65   bound to intege
2b030 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61  r 2345.** and pa
2b040 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20  rameter :xyz is 
2b050 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71  unbound, then sq
2b060 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c  lite3_sql() will
2b070 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f   return.** the o
2b080 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20  riginal string, 
2b090 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2b0a0 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65  z" but sqlite3_e
2b0b0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a  xpanded_sql().**
2b0c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45   will return "SE
2b0d0 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e  LECT 2345,NULL".
2b0e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2b0f0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2b100 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ql() interface r
2b110 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
2b120 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
2b130 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62  ry.** is availab
2b140 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  le to hold the r
2b150 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65  esult, or if the
2b160 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78   result would ex
2b170 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20  ceed the.** the 
2b180 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c  maximum string l
2b190 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64  ength determined
2b1a0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
2b1b0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  LIMIT_LENGTH]..*
2b1c0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
2b1d0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
2b1e0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
2b1f0 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74   option limits t
2b200 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f  he size of.** bo
2b210 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65 78  und parameter ex
2b220 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20  pansions.  ^The 
2b230 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41  [SQLITE_OMIT_TRA
2b240 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
2b250 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65  .** option cause
2b260 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  s sqlite3_expand
2b270 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61  ed_sql() to alwa
2b280 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  ys return NULL..
2b290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  **.** ^The strin
2b2a0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2b2b0 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20  lite3_sql(P) is 
2b2c0 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74  managed by SQLit
2b2d0 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f  e and is.** auto
2b2e0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
2b2f0 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  when the prepare
2b300 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66  d statement is f
2b310 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68  inalized..** ^Th
2b320 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2b330 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70  d by sqlite3_exp
2b340 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e  anded_sql(P), on
2b350 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
2b360 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20  .** is obtained 
2b370 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2b380 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74  lloc()] and must
2b390 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20   be free by the 
2b3a0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62  application.** b
2b3b0 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  y passing it to 
2b3c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2b3d0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2b3e0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
2b3f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2b400 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
2b410 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71  _expanded_sql(sq
2b420 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b430 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b440 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2b450 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
2b460 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
2b470 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44  tabase.** METHOD
2b480 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2b490 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b4a0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2b4b0 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
2b4c0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2b4d0 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
2b4e0 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
2b4f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b500 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
2b510 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
2b520 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2b530 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2b540 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2b550 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
2b560 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2b570 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
2b580 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
2b590 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
2b5a0 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
2b5b0 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
2b5c0 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
2b5d0 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
2b5e0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2b5f0 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
2b600 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
2b610 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
2b620 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
2b630 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
2b640 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
2b650 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2b660 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
2b670 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
2b680 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2b690 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
2b6a0 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
2b6b0 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
2b6c0 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
2b6d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2b6e0 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
2b6f0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2b700 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
2b710 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2b720 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
2b730 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
2b740 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
2b750 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
2b760 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
2b770 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
2b780 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
2b790 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
2b7a0 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
2b7b0 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
2b7c0 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
2b7d0 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
2b7e0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2b7f0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
2b800 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
2b810 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
2b820 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
2b830 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
2b840 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
2b850 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
2b860 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
2b870 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
2b880 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
2b890 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
2b8a0 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
2b8b0 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
2b8c0 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
2b8d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2b8e0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2b8f0 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
2b900 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
2b910 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
2b920 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
2b930 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
2b940 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
2b950 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
2b960 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
2b970 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2b980 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
2b990 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68   on disk..** ^Th
2b9a0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2b9b0 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66  eadonly() interf
2b9c0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2b9d0 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e   for [BEGIN] sin
2b9e0 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65  ce.** [BEGIN] me
2b9f0 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e  rely sets intern
2ba00 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68  al flags, but th
2ba10 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49  e [BEGIN|BEGIN I
2ba20 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a  MMEDIATE] and.**
2ba30 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58   [BEGIN|BEGIN EX
2ba40 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64  CLUSIVE] command
2ba50 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64  s do touch the d
2ba60 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a  atabase and so.*
2ba70 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2ba80 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e  eadonly() return
2ba90 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73  s false for thos
2baa0 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69  e commands..*/.i
2bab0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2bac0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
2bad0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2bae0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2baf0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
2bb00 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2bb10 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
2bb20 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2bb30 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2bb40 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2bb50 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
2bb60 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2bb70 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
2bb80 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2bb90 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
2bba0 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
2bbb0 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
2bbc0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
2bbd0 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
2bbe0 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f  either run to co
2bbf0 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e  mpletion (return
2bc00 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ed.** [SQLITE_DO
2bc10 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  NE] from [sqlite
2bc20 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a  3_step(S)]) nor.
2bc30 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
2bc40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2bc50 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
2bc60 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2bc70 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
2bc80 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
2bc90 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
2bca0 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
2bcb0 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
2bcc0 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
2bcd0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2bce0 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
2bcf0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2bd00 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
2bd10 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2bd20 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2bd30 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
2bd40 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2bd50 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2bd60 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
2bd70 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2bd80 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
2bd90 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
2bda0 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
2bdb0 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
2bdc0 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
2bdd0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
2bde0 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
2bdf0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
2be00 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
2be10 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
2be20 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
2be30 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
2be40 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
2be50 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
2be60 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
2be70 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
2be80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2be90 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
2bea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2beb0 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
2bec0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
2bed0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
2bee0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
2bef0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
2bf00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2bf10 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
2bf20 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
2bf30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2bf40 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
2bf50 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
2bf60 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
2bf70 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
2bf80 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
2bf90 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
2bfa0 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
2bfb0 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
2bfc0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
2bfd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2bfe0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
2bff0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
2c000 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
2c010 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
2c020 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
2c030 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2c040 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
2c050 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
2c060 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
2c070 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
2c080 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
2c090 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c0a0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
2c0b0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
2c0c0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
2c0d0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
2c0e0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2c0f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2c100 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
2c110 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
2c120 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
2c130 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
2c140 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
2c150 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
2c160 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c170 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a  3_value.  The.**
2c180 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c190 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  dup()] interface
2c1a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2c1b0 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20  construct a new 
2c1c0 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71  .** protected sq
2c1d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d  lite3_value from
2c1e0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
2c1f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2c200 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
2c210 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
2c220 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
2c230 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
2c240 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
2c250 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
2c260 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
2c270 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
2c280 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2c290 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
2c2a0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
2c2b0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
2c2c0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2c2d0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
2c2e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2c2f0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
2c300 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
2c310 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
2c320 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
2c330 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
2c340 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
2c350 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
2c360 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
2c370 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
2c380 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
2c390 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2c3a0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
2c3b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2c3c0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
2c3d0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
2c3e0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2c3f0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2c400 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2c410 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c420 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
2c430 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
2c440 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
2c450 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
2c460 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
2c470 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
2c480 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
2c490 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
2c4a0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
2c4b0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2c4c0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2c4d0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2c4e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c4f0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
2c500 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
2c510 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2c520 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c530 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
2c540 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
2c550 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
2c560 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2c570 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2c580 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2c590 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
2c5a0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
2c5b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c5c0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2c5d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c5e0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
2c5f0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
2c600 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c610 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
2c620 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2c630 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
2c640 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
2c650 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2c660 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
2c670 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2c680 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
2c690 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
2c6a0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
2c6b0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
2c6c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c6d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
2c6e0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2c6f0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
2c700 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
2c710 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
2c720 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
2c730 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
2c740 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
2c750 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
2c760 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
2c770 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
2c780 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
2c790 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
2c7a0 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
2c7b0 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
2c7c0 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
2c7d0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
2c7e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2c7f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
2c800 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2c810 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2c820 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2c830 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
2c840 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
2c850 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
2c860 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2c870 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
2c880 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
2c890 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
2c8a0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
2c8b0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2c8c0 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
2c8d0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2c8e0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
2c8f0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2c900 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
2c910 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2c920 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
2c930 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2c940 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
2c950 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
2c960 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
2c970 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
2c980 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
2c990 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
2c9a0 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
2c9b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
2c9c0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
2c9d0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
2c9e0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
2c9f0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
2ca00 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
2ca10 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f  inding}.** METHO
2ca20 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ca30 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
2ca40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
2ca50 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
2ca60 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2ca70 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
2ca80 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
2ca90 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
2caa0 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
2cab0 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
2cac0 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
2cad0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
2cae0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2caf0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
2cb00 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
2cb10 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
2cb20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
2cb30 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
2cb40 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
2cb50 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
2cb60 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
2cb70 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
2cb80 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
2cb90 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
2cba0 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
2cbb0 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
2cbc0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
2cbd0 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
2cbe0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
2cbf0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
2cc00 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
2cc10 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
2cc20 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2cc30 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
2cc40 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
2cc50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2cc60 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
2cc70 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2cc80 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
2cc90 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2cca0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
2ccb0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
2ccc0 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
2ccd0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2cce0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
2ccf0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2cd00 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2cd10 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
2cd20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
2cd30 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
2cd40 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
2cd50 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2cd60 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
2cd70 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
2cd80 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
2cd90 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
2cda0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
2cdb0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
2cdc0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
2cdd0 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
2cde0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
2cdf0 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
2ce00 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
2ce10 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
2ce20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
2ce30 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
2ce40 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ce50 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
2ce60 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
2ce70 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
2ce80 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
2ce90 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2cea0 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
2ceb0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
2cec0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
2ced0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
2cee0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
2cef0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
2cf00 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
2cf10 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
2cf20 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
2cf30 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
2cf40 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
2cf50 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
2cf60 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eter..** ^If the
2cf70 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2cf80 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2cf90 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2cfa0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2cfb0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
2cfc0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20  ind_blob() is a 
2cfd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
2cfe0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  n the fourth par
2cff0 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e  ameter.** is ign
2d000 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64  ored and the end
2d010 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73   result is the s
2d020 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62  ame as sqlite3_b
2d030 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a  ind_null()..**.*
2d040 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
2d050 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
2d060 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
2d070 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
2d080 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2d090 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
2d0a0 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
2d0b0 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
2d0c0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2d0d0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
2d0e0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
2d0f0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2d100 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
2d110 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
2d120 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2d130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d140 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2d150 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
2d160 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2d170 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
2d180 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
2d190 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2d1a0 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
2d1b0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2d1c0 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
2d1d0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2d1e0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2d1f0 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
2d200 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
2d210 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2d220 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
2d230 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
2d240 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2d250 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
2d260 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
2d270 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2d280 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73  nd_text16() or s
2d290 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d2a0 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61  64() then.** tha
2d2b0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2d2c0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
2d2d0 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
2d2e0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
2d2f0 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
2d300 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
2d310 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
2d320 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
2d330 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
2d340 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
2d350 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
2d360 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
2d370 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2d380 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
2d390 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
2d3a0 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
2d3b0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
2d3c0 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
2d3d0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
2d3e0 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
2d3f0 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
2d400 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
2d410 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2d420 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
2d430 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73  o the BLOB and s
2d440 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e  tring binding in
2d450 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61  terfaces.** is a
2d460 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
2d470 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2d480 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
2d490 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
2d4a0 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
2d4b0 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
2d4c0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
2d4d0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
2d4e0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
2d4f0 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
2d500 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20  he call to bind 
2d510 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49  API fails..** ^I
2d520 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2d530 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
2d540 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
2d550 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
2d560 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
2d570 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
2d580 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
2d590 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
2d5a0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
2d5b0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2d5c0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
2d5d0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2d5e0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
2d5f0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2d600 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
2d610 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
2d620 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
2d630 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
2d640 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
2d650 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2d660 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
2d670 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
2d680 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2d690 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2d6a0 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65  text64() must be
2d6b0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49   one of.** [SQLI
2d6c0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
2d6d0 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54  E_UTF16], [SQLIT
2d6e0 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b  E_UTF16BE], or [
2d6f0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a  SQLITE_UTF16LE].
2d700 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ** to specify th
2d710 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68  e encoding of th
2d720 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68  e text in the th
2d730 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ird parameter.  
2d740 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20  If.** the sixth 
2d750 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2d760 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2d770 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
2d780 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76  the.** allowed v
2d790 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76  alues shown abov
2d7a0 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78  e, or if the tex
2d7b0 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  t encoding is di
2d7c0 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20  fferent.** from 
2d7d0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
2d7e0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69  cified by the si
2d7f0 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74  xth parameter, t
2d800 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2d810 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
2d820 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2d830 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2d840 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
2d850 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
2d860 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
2d870 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
2d880 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
2d890 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
2d8a0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
2d8b0 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
2d8c0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
2d8d0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
2d8e0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
2d8f0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
2d900 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
2d910 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
2d920 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
2d930 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
2d940 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
2d950 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
2d960 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
2d970 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
2d980 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
2d990 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
2d9a0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
2d9b0 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
2d9c0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2d9d0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
2d9e0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
2d9f0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2da00 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
2da10 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
2da20 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
2da30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da40 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
2da50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2da60 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
2da70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2da80 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
2da90 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
2daa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2dab0 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
2dac0 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
2dad0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2dae0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
2daf0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
2db00 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
2db10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2db20 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
2db30 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
2db40 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
2db50 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2db60 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
2db70 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
2db80 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
2db90 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
2dba0 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
2dbb0 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
2dbc0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
2dbd0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
2dbe0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2dbf0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
2dc00 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2dc10 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
2dc20 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
2dc30 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
2dc40 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
2dc50 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f  .** ^[SQLITE_TOO
2dc60 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65  BIG] might be re
2dc70 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69  turned if the si
2dc80 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f  ze of a string o
2dc90 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64  r BLOB.** exceed
2dca0 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64  s limits imposed
2dcb0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
2dcc0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
2dcd0 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a  T_LENGTH]) or.**
2dce0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e   [SQLITE_MAX_LEN
2dcf0 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  GTH]..** ^[SQLIT
2dd00 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
2dd10 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
2dd20 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
2dd30 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
2dd40 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
2dd50 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2dd60 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
2dd70 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2dd80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2dd90 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2dda0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2ddb0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2ddc0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
2ddd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2dde0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2ddf0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2de00 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2de10 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2de20 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
2de30 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2de40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2de50 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
2de60 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2de70 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
2de80 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2de90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2dea0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2deb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2dec0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2ded0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
2dee0 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
2def0 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
2df00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2df10 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
2df20 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
2df30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2df40 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
2df50 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2df60 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
2df70 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
2df80 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2df90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2dfa0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e  t,const char*,in
2dfb0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2dfc0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2dfd0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
2dfe0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2dff0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2e000 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2e010 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2e020 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  nd_text64(sqlite
2e030 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2e040 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
2e050 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2e060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e070 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
2e080 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
2e090 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74  r encoding);.int
2e0a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
2e0b0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2e0c0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
2e0d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2e0e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2e0f0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
2e100 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2e110 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33   n);.int sqlite3
2e120 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34  _bind_zeroblob64
2e130 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e140 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  int, sqlite3_uin
2e150 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
2e160 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2e170 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
2e180 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e190 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2e1a0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
2e1b0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
2e1c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
2e1d0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
2e1e0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
2e1f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
2e200 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
2e210 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
2e220 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
2e230 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
2e240 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
2e250 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
2e260 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2e270 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
2e280 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2e290 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
2e2a0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
2e2b0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
2e2c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
2e2d0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
2e2e0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
2e2f0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
2e300 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
2e310 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
2e320 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
2e330 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
2e340 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
2e350 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
2e360 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
2e370 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
2e380 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
2e390 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
2e3a0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
2e3b0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
2e3c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2e3d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2e3e0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2e3f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2e400 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2e410 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
2e420 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e430 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2e440 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e450 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2e460 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2e470 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2e480 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
2e490 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
2e4a0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2e4b0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2e4c0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
2e4d0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
2e4e0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
2e4f0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
2e500 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
2e510 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
2e520 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2e530 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2e540 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
2e550 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
2e560 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
2e570 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
2e580 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
2e590 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
2e5a0 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
2e5b0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
2e5c0 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
2e5d0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
2e5e0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
2e5f0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
2e600 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
2e610 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
2e620 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
2e630 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
2e640 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2e650 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
2e660 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
2e670 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
2e680 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
2e690 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
2e6a0 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
2e6b0 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
2e6c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2e6d0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
2e6e0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
2e6f0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
2e700 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
2e710 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
2e720 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
2e730 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
2e740 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
2e750 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
2e760 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2e770 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
2e780 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
2e790 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
2e7a0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2e7b0 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
2e7c0 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
2e7d0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
2e7e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2e7f0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
2e800 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2e810 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2e820 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2e830 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2e840 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2e850 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2e860 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2e870 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e880 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2e890 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2e8a0 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
2e8b0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
2e8c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2e8d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e8e0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
2e8f0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
2e900 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54  iven Name.** MET
2e910 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e920 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
2e930 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
2e940 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
2e950 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
2e960 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
2e970 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
2e980 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
2e990 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
2e9a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2e9b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e9c0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2e9d0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
2e9e0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
2e9f0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
2ea00 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
2ea10 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2ea20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
2ea30 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
2ea40 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
2ea50 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
2ea60 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
2ea70 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
2ea80 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
2ea90 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2eaa0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2eab0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2eac0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2ead0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2eae0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2eaf0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2eb00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2eb10 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a  ter_name()]..*/.
2eb20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2eb30 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2eb40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2eb50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2eb60 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2eb70 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2eb80 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2eb90 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2eba0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2ebb0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43  e3_stmt.**.** ^C
2ebc0 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
2ebd0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
2ebe0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
2ebf0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
2ec00 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
2ec10 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2ec20 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
2ec30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ec40 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
2ec50 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
2ec60 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
2ec70 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
2ec80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
2ec90 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
2eca0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2ecb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2ecc0 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
2ecd0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2ece0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2ecf0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
2ed00 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2ed10 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2ed20 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2ed30 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2ed40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ed50 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 20  ment]. ^If this 
2ed60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2ed70 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  0, that means th
2ed80 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  e .** [prepared 
2ed90 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 72  statement] retur
2eda0 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 20  ns no data (for 
2edb0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
2edc0 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65  TE])..** ^Howeve
2edd0 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  r, just because 
2ede0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
2edf0 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20  urns a positive 
2ee00 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a  number does not.
2ee10 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65  ** mean that one
2ee20 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66   or more rows of
2ee30 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72 65   data will be re
2ee40 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45  turned.  ^A SELE
2ee50 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  CT statement.** 
2ee60 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 65  will always have
2ee70 20 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c 69   a positive sqli
2ee80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2ee90 28 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e 67  () but depending
2eea0 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 45   on the.** WHERE
2eeb0 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
2eec0 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61 62 6c  nts and the tabl
2eed0 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69  e content, it mi
2eee0 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f  ght return no ro
2eef0 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ws..**.** See al
2ef00 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2ef10 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
2ef20 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2ef30 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2ef40 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2ef50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2ef60 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2ef70 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2ef80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2ef90 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2efa0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2efb0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
2efc0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
2efd0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
2efe0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2eff0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2f000 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
2f010 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2f020 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
2f030 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2f040 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
2f050 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
2f060 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
2f070 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2f080 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
2f090 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2f0a0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
2f0b0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2f0c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2f0d0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
2f0e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2f0f0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2f100 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2f110 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
2f120 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2f130 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
2f140 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
2f150 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
2f160 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
2f170 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2f180 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
2f190 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
2f1a0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
2f1b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2f1c0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
2f1d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2f1e0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2f1f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2f200 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2f210 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2f220 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2f230 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f240 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2f250 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2f260 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
2f270 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2f280 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
2f290 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2f2a0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
2f2b0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
2f2c0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
2f2d0 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
2f2e0 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
2f2f0 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
2f300 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
2f310 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
2f320 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
2f330 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
2f340 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
2f350 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2f360 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2f370 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
2f380 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
2f390 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
2f3a0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
2f3b0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
2f3c0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
2f3d0 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
2f3e0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
2f3f0 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
2f400 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
2f410 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
2f420 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
2f430 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
2f440 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
2f450 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ext..*/.const ch
2f460 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2f470 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
2f480 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
2f490 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2f4a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2f4b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f4c0 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
2f4d0 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
2f4e0 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
2f4f0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
2f500 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2f510 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2f520 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
2f530 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
2f540 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
2f550 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
2f560 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
2f570 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
2f580 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
2f590 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2f5a0 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
2f5b0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
2f5c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2f5d0 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
2f5e0 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
2f5f0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
2f600 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
2f610 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2f620 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
2f630 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2f640 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2f650 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
2f660 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2f670 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
2f680 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
2f690 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
2f6a0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
2f6b0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
2f6c0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2f6d0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
2f6e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f6f0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
2f700 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
2f710 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f720 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2f730 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2f740 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2f750 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2f760 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2f770 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2f780 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2f790 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2f7a0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
2f7b0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2f7c0 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
2f7d0 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
2f7e0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
2f7f0 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
2f800 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
2f810 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
2f820 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
2f830 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
2f840 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
2f850 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2f860 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2f870 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
2f880 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2f890 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2f8a0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
2f8b0 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
2f8c0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
2f8d0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
2f8e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
2f8f0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
2f900 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2f910 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2f920 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
2f930 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
2f940 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2f950 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2f960 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
2f970 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
2f980 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
2f990 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
2f9a0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
2f9b0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2f9c0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2f9d0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2f9e0 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2f9f0 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2fa00 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2fa10 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2fa20 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2fa30 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2fa40 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2fa50 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2fa60 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2fa70 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2fa80 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2fa90 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2faa0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2fab0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2fac0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2fad0 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2fae0 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2faf0 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2fb00 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2fb10 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2fb20 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2fb30 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2fb40 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2fb50 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2fb60 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2fb70 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2fb80 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2fb90 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2fba0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2fbb0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2fbc0 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2fbd0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2fbe0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2fbf0 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2fc00 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2fc10 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2fc20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2fc30 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2fc40 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2fc50 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2fc60 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2fc70 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2fc80 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2fc90 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2fca0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2fcb0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2fcc0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2fcd0 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2fce0 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2fcf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fd00 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2fd10 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2fd20 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2fd30 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2fd40 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
2fd50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2fd60 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2fd70 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2fd80 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2fd90 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2fda0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2fdb0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2fdc0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2fdd0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2fde0 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2fdf0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2fe00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2fe10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2fe20 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2fe30 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2fe40 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2fe50 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2fe60 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2fe70 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2fe80 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2fe90 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2fea0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2feb0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2fec0 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2fed0 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2fee0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2fef0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ff00 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
2ff10 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2ff20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2ff30 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2ff40 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
2ff50 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2ff60 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
2ff70 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
2ff80 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
2ff90 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
2ffa0 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
2ffb0 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
2ffc0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2ffd0 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
2ffe0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2fff0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
30000 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
30010 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
30020 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
30030 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
30040 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
30050 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
30060 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
30070 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
30080 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
30090 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
300a0 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
300b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
300c0 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
300d0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
300e0 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
300f0 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
30100 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
30110 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
30120 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
30130 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
30140 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
30150 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
30160 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
30170 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
30180 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
30190 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
301a0 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
301b0 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
301c0 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
301d0 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
301e0 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
301f0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
30200 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
30210 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
30220 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
30230 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
30240 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
30250 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
30260 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
30270 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
30280 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
30290 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
302a0 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
302b0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
302c0 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
302d0 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
302e0 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
302f0 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
30300 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
30310 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
30320 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
30330 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
30340 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
30350 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73   values..*/.cons
30360 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
30370 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
30380 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
30390 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
303a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
303b0 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
303c0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
303d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
303e0 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
303f0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48  tatement.** METH
30400 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
30410 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
30420 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30430 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
30440 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
30450 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
30460 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
30470 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30480 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
30490 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
304a0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
304b0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
304c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
304d0 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
304e0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
304f0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
30500 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
30510 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
30520 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
30530 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
30540 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
30550 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
30560 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
30570 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
30580 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
30590 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
305a0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
305b0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
305c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
305d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
305e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
305f0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
30600 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
30610 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30620 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
30630 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
30640 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
30650 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
30660 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
30670 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
30680 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
30690 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
306a0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
306b0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
306c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
306d0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
306e0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
306f0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
30700 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
30710 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
30720 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
30730 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
30740 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
30750 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
30760 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
30770 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
30780 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
30790 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
307a0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
307b0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
307c0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
307d0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
307e0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
307f0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
30800 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
30810 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
30820 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
30830 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
30840 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
30850 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
30860 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
30870 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
30880 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
30890 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
308a0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
308b0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
308c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
308d0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
308e0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
308f0 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
30900 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
30910 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
30920 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
30930 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
30940 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
30950 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
30960 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
30970 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
30980 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
30990 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
309a0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
309b0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
309c0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
309d0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
309e0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
309f0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
30a00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
30a10 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
30a20 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
30a30 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
30a40 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
30a50 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
30a60 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
30a70 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
30a80 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
30a90 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
30aa0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
30ab0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
30ac0 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
30ad0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
30ae0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
30af0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
30b00 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
30b10 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
30b20 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
30b30 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
30b40 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
30b50 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
30b60 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
30b70 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
30b80 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
30b90 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
30ba0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
30bb0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
30bc0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
30bd0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
30be0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
30bf0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
30c00 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
30c10 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
30c20 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
30c30 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
30c40 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
30c50 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
30c60 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
30c70 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
30c80 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
30c90 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
30ca0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
30cb0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
30cc0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
30cd0 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
30ce0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
30cf0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
30d00 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
30d10 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
30d20 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
30d30 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
30d40 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
30d50 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
30d60 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
30d70 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
30d80 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
30d90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
30da0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
30db0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
30dc0 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
30dd0 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
30de0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
30df0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
30e00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
30e10 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
30e20 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
30e30 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
30e40 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
30e50 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
30e60 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
30e70 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
30e80 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
30e90 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
30ea0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
30eb0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
30ec0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30ed0 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
30ee0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
30ef0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
30f00 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
30f10 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
30f20 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
30f30 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
30f40 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
30f50 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
30f60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30f70 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
30f80 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
30f90 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
30fa0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
30fb0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
30fc0 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
30fd0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
30fe0 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
30ff0 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
31000 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
31010 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31020 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
31030 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
31040 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
31050 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
31060 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
31070 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
31080 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73 69  But after [versi
31090 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64  on 3.6.23.1] ([d
310a0 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c  ateof:3.6.23.1],
310b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
310c0 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c  () began.** call
310d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
310e0 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61  et()] automatica
310f0 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63  lly in this circ
31100 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a  umstance rather.
31110 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e  ** than returnin
31120 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  g [SQLITE_MISUSE
31130 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20  ].  This is not 
31140 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d  considered a com
31150 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72  patibility.** br
31160 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20  eak because any 
31170 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74  application that
31180 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61   ever receives a
31190 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  n SQLITE_MISUSE 
311a0 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b  error.** is brok
311b0 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e  en by definition
311c0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
311d0 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63  MIT_AUTORESET] c
311e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
311f0 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  on.** can be use
31200 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65  d to restore the
31210 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
31220 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
31230 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
31240 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
31250 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
31260 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
31270 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
31280 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
31290 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
312a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
312b0 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
312c0 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
312d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
312e0 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
312f0 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
31300 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
31310 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
31320 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
31330 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
31340 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
31350 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
31360 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
31370 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
31380 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
31390 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
313a0 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
313b0 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
313c0 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
313d0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
313e0 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
313f0 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
31400 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
31410 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
31420 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
31430 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
31440 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
31450 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
31460 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
31470 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
31480 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
31490 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
314a0 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
314b0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
314c0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
314d0 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
314e0 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
314f0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
31500 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
31510 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
31520 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
31530 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
31540 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
31550 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31560 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
31570 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
31580 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31590 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
315a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
315b0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
315c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
315d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
315e0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
315f0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
31600 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
31610 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31620 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
31630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
31640 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
31650 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
31660 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
31670 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
31680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
31690 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
316a0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
316b0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
316c0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
316d0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
316e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
316f0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
31700 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
31710 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
31720 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
31730 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
31740 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
31750 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
31760 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
31770 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
31780 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
31790 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
317a0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
317b0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
317c0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
317d0 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
317e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
317f0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
31800 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
31810 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
31820 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
31830 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
31840 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
31850 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
31860 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
31870 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
31880 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
31890 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
318a0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
318b0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
318c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
318d0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
318e0 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
318f0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
31900 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
31910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
31920 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
31930 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
31940 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
31950 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
31960 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
31970 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
31980 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
31990 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
319a0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
319b0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
319c0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
319d0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
319e0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
319f0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
31a00 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
31a10 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
31a20 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
31a30 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
31a40 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
31a50 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
31a60 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
31a70 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
31a80 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
31a90 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
31aa0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
31ab0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
31ac0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
31ad0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
31ae0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
31af0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
31b00 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
31b10 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
31b20 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
31b30 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
31b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
31b50 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
31b60 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
31b70 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
31b80 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
31b90 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
31ba0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
31bb0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
31bc0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
31bd0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
31be0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
31bf0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
31c00 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
31c10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31c20 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
31c30 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
31c40 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
31c50 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
31c60 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
31c70 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31c80 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
31c90 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
31ca0 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
31cb0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
31cc0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
31cd0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
31ce0 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
31cf0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
31d00 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
31d10 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
31d20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31d30 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
31d40 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
31d50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
31d60 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
31d70 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
31d80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
31d90 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
31da0 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
31db0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
31dc0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
31dd0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
31de0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
31df0 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
31e00 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
31e10 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
31e20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
31e30 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
31e40 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
31e50 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
31e60 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
31e70 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
31e80 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
31e90 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
31ea0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
31eb0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
31ec0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
31ed0 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
31ee0 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
31ef0 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
31f00 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
31f10 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
31f20 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
31f30 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
31f40 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
31f50 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
31f60 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
31f70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
31f80 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
31f90 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
31fa0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
31fb0 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
31fc0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31fd0 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
31fe0 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
31ff0 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
32000 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
32010 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
32020 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32030 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
32040 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
32050 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
32060 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
32070 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
32080 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
32090 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
320a0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
320b0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
320c0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
320d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
320e0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
320f0 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
32100 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
32110 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
32120 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
32130 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
32140 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
32150 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
32160 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
32170 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
32180 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
32190 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
321a0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
321b0 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
321c0 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
321d0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
321e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
321f0 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
32200 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
32210 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
32220 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
32230 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
32240 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
32250 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
32260 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
32270 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
32280 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
32290 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
322a0 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
322b0 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
322c0 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
322d0 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
322e0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
322f0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
32300 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
32310 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
32320 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
32330 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
32340 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
32350 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
32360 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
32370 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
32380 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
32390 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
323a0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
323b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
323c0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
323d0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
323e0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
323f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
32400 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
32410 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
32420 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
32430 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
32440 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32450 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
32460 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
32470 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
32480 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
32490 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
324a0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
324b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
324c0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
324d0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
324e0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
324f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32500 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
32510 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
32520 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
32530 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
32540 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
32550 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
32560 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
32570 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
32580 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
32590 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
325a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
325b0 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
325c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
325d0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
325e0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
325f0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
32600 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32610 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
32620 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
32630 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
32640 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
32650 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
32660 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
32670 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
32680 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32690 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
326a0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
326b0 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
326c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
326d0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
326e0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
326f0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
32700 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
32710 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
32720 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
32730 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
32740 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
32750 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
32760 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
32770 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
32780 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
32790 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
327a0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
327b0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
327c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
327d0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
327e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
327f0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
32800 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32810 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
32820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32830 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
32840 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
32850 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
32860 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
32870 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
32880 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
32890 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
328a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
328b0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
328c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
328d0 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
328e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
328f0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
32900 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
32910 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
32920 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
32930 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
32940 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32950 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
32960 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
32970 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
32980 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
32990 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
329a0 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
329b0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
329c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
329d0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
329e0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
329f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
32a00 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67  **.** <b>Warning
32a10 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63  :</b> ^The objec
32a20 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
32a30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
32a40 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
32a50 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
32a60 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
32a70 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74  ct.  In a multit
32a80 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d  hreaded environm
32a90 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f  ent,.** an unpro
32aa0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
32ab0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
32ac0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66  only be used saf
32ad0 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  ely with.** [sql
32ae0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
32af0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32b00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
32b10 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
32b20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32b30 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
32b40 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
32b50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
32b60 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
32b70 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
32b80 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
32b90 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
32ba0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
32bb0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
32bc0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
32bd0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
32be0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
32bf0 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
32c00 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
32c10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
32c20 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
32c30 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
32c40 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
32c50 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
32c60 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
32c70 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
32c80 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
32c90 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
32ca0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
32cb0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
32cc0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
32cd0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
32ce0 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
32cf0 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
32d00 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
32d10 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
32d20 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
32d30 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
32d40 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
32d50 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
32d60 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
32d70 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
32d80 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
32d90 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
32da0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
32db0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
32dc0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
32dd0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
32de0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
32df0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
32e00 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
32e10 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
32e20 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
32e30 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
32e40 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
32e50 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
32e60 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
32e70 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
32e80 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
32e90 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
32ea0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
32eb0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
32ec0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
32ed0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
32ee0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
32ef0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
32f00 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
32f10 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
32f20 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
32f30 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
32f40 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
32f50 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
32f60 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
32f70 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
32f80 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
32f90 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
32fa0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
32fb0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
32fc0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
32fd0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
32fe0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
32ff0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
33000 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
33010 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
33020 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42  <td> [CAST] to B
33030 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  LOB.** <tr><td> 
33040 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
33050 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
33060 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
33070 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
33080 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
33090 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
330a0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
330b0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
330c0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
330d0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
330e0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
330f0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
33100 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
33110 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
33120 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
33130 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
33140 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
33150 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
33160 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
33170 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
33180 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
33190 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
331a0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
331b0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  e>)^.**.** Note 
331c0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
331d0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
331e0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
331f0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
33200 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
33210 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
33220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33230 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
33240 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33250 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
33260 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
33270 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
33280 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
33290 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
332a0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
332b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
332c0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
332d0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
332e0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
332f0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
33300 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
33310 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
33320 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
33330 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
33340 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
33350 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
33360 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
33370 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
33380 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
33390 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
333a0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
333b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
333c0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
333d0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
333e0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
333f0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
33400 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
33410 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
33420 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
33430 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
33440 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
33450 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
33460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33470 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
33480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33490 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
334a0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
334b0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
334c0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
334d0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
334e0 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
334f0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
33500 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
33510 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
33520 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
33530 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
33540 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
33550 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
33560 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
33570 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
33580 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
33590 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
335a0 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
335b0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
335c0 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
335d0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
335e0 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
335f0 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
33600 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
33610 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
33620 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
33630 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
33640 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
33650 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
33660 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63  The safest polic
33670 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
33680 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
33690 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
336a0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
336b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
336c0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
336d0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
336e0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
336f0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
33700 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
33710 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
33720 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
33730 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
33740 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
33750 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33760 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
33770 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
33780 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
33790 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
337a0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
337b0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
337c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
337d0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
337e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
337f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
33800 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
33810 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
33820 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
33830 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
33840 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
33850 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33860 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
33870 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
33880 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
33890 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
338a0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
338b0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
338c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
338d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
338e0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
338f0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
33900 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
33910 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
33920 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
33930 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33940 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
33950 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
33960 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
33970 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
33980 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
33990 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
339a0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
339b0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
339c0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
339d0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
339e0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
339f0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
33a00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
33a10 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
33a20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
33a30 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
33a40 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
33a50 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
33a60 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
33a70 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61   <em>not</em> pa
33a80 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
33a90 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
33aa0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
33ab0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
33ac0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
33ad0 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
33ae0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
33af0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
33b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
33b10 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
33b20 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
33b30 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
33b40 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
33b50 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
33b60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
33b70 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
33b80 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
33b90 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
33ba0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
33bb0 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
33bc0 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
33bd0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
33be0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
33bf0 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
33c00 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
33c10 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63  E_NOMEM].)^.*/.c
33c20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
33c30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
33c40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33c50 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
33c60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33c70 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
33c80 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
33c90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33ca0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
33cb0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
33cc0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
33cd0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
33ce0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33cf0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
33d00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
33d10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33d20 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
33d30 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
33d40 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
33d50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
33d60 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
33d70 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
33d80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
33d90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33da0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
33db0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
33dc0 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
33dd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
33de0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
33df0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
33e00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33e10 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
33e20 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
33e30 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
33e40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
33e50 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
33e60 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
33e70 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
33e80 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53  nt Object.** DES
33e90 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
33ea0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
33eb0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
33ec0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
33ed0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
33ee0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
33ef0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
33f00 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
33f10 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
33f20 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
33f30 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
33f40 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
33f50 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
33f60 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
33f70 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
33f80 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
33f90 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
33fa0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
33fb0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
33fc0 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
33fd0 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
33fe0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33ff0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
34000 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
34010 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
34020 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
34030 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
34040 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34050 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
34060 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
34070 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
34080 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
34090 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
340a0 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
340b0 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
340c0 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
340d0 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
340e0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
340f0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
34100 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
34110 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
34120 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
34130 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
34140 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
34150 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
34160 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
34170 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
34180 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
34190 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
341a0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
341b0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
341c0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
341d0 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
341e0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
341f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
34200 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
34210 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
34220 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
34230 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
34240 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
34250 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
34260 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
34270 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
34280 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
34290 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
342a0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
342b0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
342c0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
342d0 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
342e0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
342f0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
34300 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
34310 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
34320 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
34330 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
34340 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
34350 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
34360 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
34370 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
34380 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
34390 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
343a0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  _stmt.**.** The 
343b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
343c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
343d0 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
343e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
343f0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
34400 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
34410 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
34420 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
34430 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
34440 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
34450 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
34460 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
34470 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
34480 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
34490 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
344a0 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
344b0 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
344c0 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
344d0 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
344e0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
344f0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
34500 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
34510 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
34520 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
34530 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
34540 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
34550 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
34560 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
34570 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
34580 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
34590 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
345a0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
345b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
345c0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
345d0 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
345e0 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
345f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
34600 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
34610 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
34620 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
34630 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
34640 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
34650 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
34660 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
34670 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
34680 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
34690 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
346a0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
346b0 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
346c0 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
346d0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
346e0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
346f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
34700 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
34710 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
34720 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
34730 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
34740 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
34750 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
34760 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
34770 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34780 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
34790 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
347a0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
347b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
347c0 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
347d0 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
347e0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
347f0 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
34800 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
34810 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
34820 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34830 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
34840 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
34850 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34860 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
34870 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34880 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  3.**.** ^These f
34890 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
348a0 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
348b0 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
348c0 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
348d0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
348e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
348f0 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
34900 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
34910 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
34920 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
34930 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
34940 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
34950 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
34960 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
34970 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
34980 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
34990 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
349a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
349b0 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
349c0 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
349d0 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
349e0 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
349f0 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
34a00 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
34a10 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
34a20 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
34a30 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
34a40 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
34a50 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
34a60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
34a70 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
34a80 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
34a90 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
34aa0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
34ab0 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
34ac0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
34ad0 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
34ae0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34af0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
34b00 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
34b10 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
34b20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
34b30 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
34b40 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
34b50 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
34b60 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
34b70 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
34b80 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
34b90 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
34ba0 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
34bb0 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
34bc0 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
34bd0 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
34be0 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
34bf0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
34c00 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
34c10 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
34c20 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
34c30 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
34c40 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
34c50 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
34c60 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
34c70 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
34c80 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
34c90 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
34ca0 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
34cb0 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
34cc0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
34cd0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
34ce0 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
34cf0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
34d00 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
34d10 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
34d20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
34d30 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
34d40 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
34d50 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
34d60 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
34d70 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
34d80 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
34d90 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
34da0 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
34db0 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
34dc0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
34dd0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
34de0 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
34df0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
34e00 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
34e10 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
34e20 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
34e30 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
34e40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
34e50 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
34e60 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
34e70 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
34e80 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
34e90 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
34ea0 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
34eb0 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
34ec0 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
34ed0 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
34ee0 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68  on should set th
34ef0 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  is parameter to.
34f00 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
34f10 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74  LE] if the funct
34f20 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
34f30 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b  on invokes .** [
34f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
34f50 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16le()] on an 
34f60 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54  input, or [SQLIT
34f70 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68  E_UTF16BE] if th
34f80 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
34f90 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c  ion invokes [sql
34fa0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34fb0 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6be()] on an inp
34fc0 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  ut, or.** [SQLIT
34fd0 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c  E_UTF16] if [sql
34fe0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34ff0 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72  6()] is used, or
35000 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a   [SQLITE_UTF8].*
35010 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54  * otherwise.  ^T
35020 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
35030 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
35040 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
35050 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64  times using.** d
35060 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72  ifferent preferr
35070 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
35080 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  s, with differen
35090 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
350a0 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e  s for.** each en
350b0 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e  coding..** ^When
350c0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
350d0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
350e0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
350f0 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
35100 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
35110 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
35120 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
35130 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
35140 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
35150 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
35160 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74  arameter may opt
35170 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20  ionally be ORed 
35180 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54  with [SQLITE_DET
35190 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74  ERMINISTIC].** t
351a0 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68  o signal that th
351b0 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  e function will 
351c0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
351d0 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69  e same result gi
351e0 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ven.** the same 
351f0 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20  inputs within a 
35200 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
35210 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20  ment.  Most SQL 
35220 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a  functions are.**
35230 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
35240 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72   The built-in [r
35250 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e  andom()] SQL fun
35260 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d  ction is an exam
35270 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63  ple of a.** func
35280 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74  tion that is not
35290 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
352a0 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72   The SQLite quer
352b0 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c  y planner is abl
352c0 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20  e to.** perform 
352d0 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d  additional optim
352e0 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65  izations on dete
352f0 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69  rministic functi
35300 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f  ons, so use.** o
35310 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45  f the [SQLITE_DE
35320 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61  TERMINISTIC] fla
35330 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  g is recommended
35340 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e   where possible.
35350 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
35360 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
35370 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
35380 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
35390 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
353a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
353b0 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
353c0 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
353d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
353e0 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
353f0 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
35400 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
35410 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
35420 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
35430 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
35440 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
35450 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
35460 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
35470 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
35480 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
35490 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
354a0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
354b0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
354c0 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
354d0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
354e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
354f0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
35500 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
35510 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
35520 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
35530 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
35540 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
35550 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
35560 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
35570 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
35580 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
35590 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
355a0 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
355b0 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
355c0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
355d0 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
355e0 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
355f0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
35600 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
35610 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
35620 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
35630 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35640 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
35650 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
35660 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
35670 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
35680 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
35690 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
356a0 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
356b0 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
356c0 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
356d0 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
356e0 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
356f0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
35700 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
35710 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
35720 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
35730 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
35740 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
35750 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35760 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
35770 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
35780 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
35790 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
357a0 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
357b0 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
357c0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
357d0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
357e0 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
357f0 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
35800 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
35810 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
35820 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
35830 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
35840 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
35850 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
35860 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
35870 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35880 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
35890 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
358a0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
358b0 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
358c0 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
358d0 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
358e0 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
358f0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
35900 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
35910 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
35920 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
35930 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
35940 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
35950 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
35960 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
35970 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
35980 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
35990 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
359a0 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
359b0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
359c0 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
359d0 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
359e0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
359f0 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
35a00 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
35a10 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
35a20 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
35a30 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
35a40 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
35a50 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
35a60 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
35a70 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
35a80 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
35a90 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
35aa0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
35ab0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
35ac0 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
35ad0 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
35ae0 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
35af0 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
35b00 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
35b10 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
35b20 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
35b30 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
35b40 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
35b50 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
35b60 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
35b70 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
35b80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35b90 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
35ba0 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
35bb0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35bc0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
35bd0 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
35be0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
35bf0 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
35c00 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
35c10 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
35c20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35c30 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
35c40 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
35c50 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
35c60 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
35c70 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
35c80 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  g..*/.int sqlite
35c90 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35ca0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
35cb0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
35cc0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
35cd0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
35ce0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
35cf0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
35d00 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
35d10 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
35d20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
35d30 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
35d40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35d50 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35d60 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
35d70 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
35d80 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
35d90 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35da0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
35db0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
35dc0 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
35dd0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
35de0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
35df0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
35e00 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
35e10 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
35e20 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
35e30 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
35e40 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
35e50 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
35e60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
35e70 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
35e80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35e90 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
35ea0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35eb0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
35ec0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
35ed0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
35ee0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
35ef0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
35f00 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
35f10 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
35f20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
35f30 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
35f40 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
35f50 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
35f60 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
35f70 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
35f80 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
35f90 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
35fa0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
35fb0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
35fc0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
35fd0 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
35fe0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
35ff0 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
36000 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
36010 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
36020 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
36030 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
36040 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
36050 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
36060 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49         1    /* I
36070 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36  MP: R-37514-3556
36080 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  6 */.#define SQL
36090 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
360a0 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20     2    /* IMP: 
360b0 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f  R-03371-37637 */
360c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
360d0 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
360e0 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31      /* IMP: R-51
360f0 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65  971-34154 */.#de
36100 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
36110 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
36120 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
36130 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
36140 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
36150 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
36160 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a  * Deprecated */.
36170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
36180 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
36190 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
361a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
361b0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
361c0 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
361d0 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Flags.**.** The
361e0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  se constants may
361f0 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65   be ORed togethe
36200 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  r with the .** [
36210 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72  SQLITE_UTF8 | pr
36220 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
36230 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f  oding] as the fo
36240 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  urth argument.**
36250 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
36260 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
36270 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36280 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20  _function16()], 
36290 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
362a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
362b0 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  2()]..*/.#define
362c0 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e   SQLITE_DETERMIN
362d0 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a  ISTIC    0x800..
362e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
362f0 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
36300 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
36310 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
36320 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
36330 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
36340 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
36350 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
36360 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
36370 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
36380 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
36390 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
363a0 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
363b0 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
363c0 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
363d0 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
363e0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
363f0 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20  .  To encourage 
36400 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61  programmers to a
36410 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75  void.** these fu
36420 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c  nctions, we will
36430 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61   not explain wha
36440 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
36450 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
36460 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
36470 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
36480 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
36490 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
364a0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
364b0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
364c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
364d0 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
364e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
364f0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
36500 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
36510 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
36520 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
36530 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
36540 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
36550 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
36560 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
36570 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
36580 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
36590 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
365a0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
365b0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
365c0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
365d0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
365e0 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20  64,int),.       
365f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
36600 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
36610 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
36620 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
36630 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 65  aining SQL Value
36640 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
36650 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
36660 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
36670 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
36680 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
36690 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
366a0 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
366b0 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
366c0 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
366d0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
366e0 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
366f0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
36700 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  gate.  .**.** Th
36710 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
36720 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
36730 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
36740 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
36750 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
36760 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36770 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
36780 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36790 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
367a0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
367b0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
367c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
367d0 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
367e0 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
367f0 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
36800 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
36810 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
36820 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
36830 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36840 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
36850 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
36860 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
36870 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
36880 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
36890 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
368a0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
368b0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
368c0 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
368d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
368e0 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
368f0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
36900 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
36910 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36920 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
36930 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
36940 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
36950 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
36960 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36970 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
36980 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
36990 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
369a0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
369b0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
369c0 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
369d0 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
369e0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
369f0 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
36a00 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
36a10 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
36a20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36a30 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
36a40 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
36a50 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
36a60 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
36a70 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
36a80 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
36a90 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
36aa0 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
36ab0 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
36ac0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
36ad0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
36ae0 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
36af0 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
36b00 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
36b10 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
36b20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
36b30 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
36b40 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
36b50 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
36b60 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
36b70 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
36b80 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
36b90 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
36ba0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
36bb0 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
36bc0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
36bd0 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
36be0 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
36bf0 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
36c00 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
36c10 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
36c20 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
36c30 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
36c40 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
36c50 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
36c60 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
36c70 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
36c80 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
36c90 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
36ca0 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
36cb0 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
36cc0 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
36cd0 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
36ce0 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
36cf0 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
36d00 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
36d10 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
36d20 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
36d30 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
36d40 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
36d50 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
36d60 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
36d70 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
36d80 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
36d90 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
36da0 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
36db0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
36dc0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
36dd0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
36de0 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
36df0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
36e00 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
36e10 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
36e20 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
36e30 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
36e40 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
36e50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
36e60 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
36e70 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
36e80 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
36e90 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
36ea0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
36eb0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
36ec0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
36ed0 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
36ee0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
36ef0 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
36f00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
36f10 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
36f20 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
36f30 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
36f40 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
36f50 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
36f60 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
36f70 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
36f80 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
36f90 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
36fa0 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
36fb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
36fc0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
36fd0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
36fe0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
36ff0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
37000 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
37010 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
37020 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37030 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
37040 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
37050 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
37060 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
37070 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
37080 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
37090 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
370a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
370b0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
370c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
370d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
370e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
370f0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
37100 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
37110 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
37120 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
37130 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
37140 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
37150 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
37160 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
37170 69 6e 67 20 54 68 65 20 53 75 62 74 79 70 65 20  ing The Subtype 
37180 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  Of SQL Values.**
37190 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
371a0 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65  _value.**.** The
371b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73   sqlite3_value_s
371c0 75 62 74 79 70 65 28 56 29 20 66 75 6e 63 74 69  ubtype(V) functi
371d0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  on returns the s
371e0 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e  ubtype for.** an
371f0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
37200 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
37210 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e 20  on] argument V. 
37220 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20   The subtype.** 
37230 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20  information can 
37240 62 65 20 75 73 65 64 20 74 6f 20 70 61 73 73 20  be used to pass 
37250 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74  a limited amount
37260 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d   of context from
37270 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63  .** one SQL func
37280 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e  tion to another.
37290 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74    Use the [sqlit
372a0 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70  e3_result_subtyp
372b0 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  e()].** routine 
372c0 74 6f 20 73 65 74 20 74 68 65 20 73 75 62 74 79  to set the subty
372d0 70 65 20 66 6f 72 20 74 68 65 20 72 65 74 75 72  pe for the retur
372e0 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51  n value of an SQ
372f0 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  L function..**.*
37300 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e  * SQLite makes n
37310 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79 70 65  o use of subtype
37320 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65 72   itself.  It mer
37330 65 6c 79 20 70 61 73 73 65 73 20 74 68 65 20 73  ely passes the s
37340 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74  ubtype.** from t
37350 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65  he result of one
37360 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
37370 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
37380 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  on] into the.** 
37390 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65 72  input of another
373a0 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64 20 69 6e  ..*/.unsigned in
373b0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
373c0 73 75 62 74 79 70 65 28 73 71 6c 69 74 65 33 5f  subtype(sqlite3_
373d0 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
373e0 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41  CAPI3REF: Copy A
373f0 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75  nd Free SQL Valu
37400 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
37410 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a  lite3_value.**.*
37420 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
37430 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65  alue_dup(V) inte
37440 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
37450 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
37460 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
37470 65 63 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e  ect D and return
37480 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
37490 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20  hat copy.  ^The 
374a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
374b0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61  returned.** is a
374c0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
374d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
374e0 74 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e  t even if the in
374f0 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e  put is not..** ^
37500 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
37510 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61  e_dup(V) interfa
37520 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  ce returns NULL 
37530 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20  if V is NULL or 
37540 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  if a.** memory a
37550 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e  llocation fails.
37560 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37570 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56  te3_value_free(V
37580 29 20 69 6e 74 65 72 66 61 63 65 20 66 72 65 65  ) interface free
37590 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61  s an [sqlite3_va
375a0 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
375b0 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
375c0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
375d0 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20  _value_dup()].  
375e0 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20  ^If V is a NULL 
375f0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20  pointer.** then 
37600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72  sqlite3_value_fr
37610 65 65 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c  ee(V) is a harml
37620 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71  ess no-op..*/.sq
37630 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
37640 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 63  ite3_value_dup(c
37650 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
37660 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
37670 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71  e3_value_free(sq
37680 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
37690 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
376a0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
376b0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
376c0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
376d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
376e0 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** Implementatio
376f0 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  ns of aggregate 
37700 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
37710 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  e this.** routin
37720 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
37730 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67  mory for storing
37740 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
37750 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
37760 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
37770 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37780 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69  t(C,N) routine i
37790 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72  s called .** for
377a0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
377b0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
377c0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f  , SQLite.** allo
377d0 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72  cates N of memor
377e0 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
377f0 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
37800 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
37810 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d  .** to the new m
37820 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e  emory. ^On secon
37830 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
37840 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
37850 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37860 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
37870 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
37880 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
37890 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  e,.** the same b
378a0 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
378b0 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72  d.  Sqlite3_aggr
378c0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
378d0 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63  is normally.** c
378e0 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  alled once for e
378f0 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ach invocation o
37900 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c  f the xStep call
37910 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e  back and then on
37920 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77  e.** last time w
37930 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hen the xFinal c
37940 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
37950 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72  ed.  ^(When no r
37960 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20  ows match.** an 
37970 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c  aggregate query,
37980 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c   the xStep() cal
37990 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67  lback of the agg
379a0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a  regate function.
379b0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
379c0 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65  n is never calle
379d0 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69  d and xFinal() i
379e0 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79  s called exactly
379f0 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f   once..** In tho
37a00 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65  se cases, sqlite
37a10 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37a20 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63  ext() might be c
37a30 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
37a40 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d   first time from
37a50 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29   within xFinal()
37a60 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
37a70 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
37a80 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
37a90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
37aa0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a  NULL pointer .**
37ab0 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c   when first call
37ac0 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20  ed if N is less 
37ad0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
37ae0 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
37af0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
37b00 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
37b10 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
37b20 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
37b30 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
37b40 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37b50 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
37b60 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
37b70 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
37b80 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
37b90 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
37ba0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
37bb0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
37bc0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
37bd0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37be0 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
37bf0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
37c00 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
37c10 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
37c20 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
37c30 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57  allocation.)^  W
37c40 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c  ithin the xFinal
37c50 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73   callback, it is
37c60 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65   customary to se
37c70 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c  t.** N=0 in call
37c80 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  s to sqlite3_agg
37c90 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
37ca0 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a  ,N) so that no .
37cb0 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d  ** pointless mem
37cc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
37cd0 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  occur..**.** ^SQ
37ce0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
37cf0 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d  ly frees the mem
37d00 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
37d10 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67   .** sqlite3_agg
37d20 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
37d30 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
37d40 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  ate query conclu
37d50 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
37d60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d  irst parameter m
37d70 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66  ust be a copy of
37d80 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
37d90 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
37da0 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
37db0 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
37dc0 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
37dd0 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20  to the xStep or 
37de0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
37df0 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
37e00 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
37e10 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
37e20 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
37e30 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
37e40 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
37e50 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
37e60 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
37e70 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
37e80 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
37e90 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
37ea0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37eb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37ec0 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
37ed0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37ee0 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
37ef0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
37f00 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
37f10 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  xt.**.** ^The sq
37f20 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
37f30 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
37f40 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
37f50 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
37f60 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
37f70 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
37f80 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
37f90 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
37fa0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37fb0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
37fc0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
37fd0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
37fe0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
37ff0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
38000 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
38010 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
38020 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
38030 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
38040 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
38050 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
38060 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
38070 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
38080 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
38090 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
380a0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
380b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
380c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
380d0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
380e0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
380f0 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
38100 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
38110 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
38120 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
38130 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
38140 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
38150 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
38160 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
38170 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38180 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
38190 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
381a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
381b0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
381c0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
381d0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
381e0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
381f0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
38200 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
38210 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
38220 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
38230 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
38240 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
38250 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
38260 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38270 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
38280 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45  liary Data.** ME
38290 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
382a0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ntext.**.** Thes
382b0 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  e functions may 
382c0 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d  be used by (non-
382d0 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66  aggregate) SQL f
382e0 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
382f0 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
38300 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
38310 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
38320 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
38330 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
38340 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
38350 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
38360 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
38370 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
38380 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
38390 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
383a0 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
383b0 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
383c0 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rved.  An exampl
383d0 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68  e.** of where th
383e0 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66  is might be usef
383f0 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c  ul is in a regul
38400 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
38410 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  tching.** functi
38420 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
38430 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
38440 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
38450 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  on can be stored
38460 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
38470 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
38480 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
38490 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73  ng.  .** Then as
384a0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74   long as the pat
384b0 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61  tern string rema
384c0 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a  ins the same,.**
384d0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   the compiled re
384e0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
384f0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
38500 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
38510 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
38520 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a   same function..
38530 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
38540 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
38550 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
38560 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
38570 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
38580 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
38590 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
385a0 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
385b0 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
385c0 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
385d0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
385e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
385f0 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69  ion. ^If there i
38600 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a  s no metadata.**
38610 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
38620 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72   the function ar
38630 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c  gument, this sql
38640 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
38650 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
38660 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
38670 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
38680 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
38690 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
386a0 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
386b0 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f  P as metadata fo
386c0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
386d0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
386e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
386f0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75  d function.  ^Su
38700 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
38710 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
38720 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65  _auxdata(C,N) re
38730 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20  turn P from the 
38740 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
38750 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
38760 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c  ta(C,N,P,X) call
38770 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
38780 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20   is still valid 
38790 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68  or.** NULL if th
387a0 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  e metadata has b
387b0 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  een discarded..*
387c0 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61  * ^After each ca
387d0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
387e0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
387f0 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f  X) where X is no
38800 74 20 4e 55 4c 4c 2c