/ Hex Artifact Content
Login

Artifact dfe8c1b4ac66635495ec9a6a7205fcb0f27f4451:


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 20 20  sqlite_int64;.  
2960: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2970: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2980: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2990: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
29a0: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
29b0: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
29c0: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
29d0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
29e0: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
29f0: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2a00: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2a10: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2a20: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2a30: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2a40: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2a50: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2a60: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2a70: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2a80: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2a90: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2aa0: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2ab0: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2ac0: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2ad0: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2ae0: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2af0: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2b00: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2b10: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2b20: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2b30: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2b40: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2b50: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2b60: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2b70: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2b80: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2b90: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2ba0: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2bb0: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2bc0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2bd0: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2be0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2bf0: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2c00: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2c10: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2c20: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2c30: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2c40: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2c50: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2c60: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2c70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2c80: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2c90: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2ca0: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2cb0: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2cc0: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2cd0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2ce0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2cf0: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2d00: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2d10: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2d20: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2d30: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2d40: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2d50: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2d60: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2d70: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2d80: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2d90: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2da0: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2db0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2dc0: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2dd0: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2de0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2df0: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2e00: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2e10: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2e20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e30: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2e40: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2e50: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2e60: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2e70: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2e80: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2e90: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2ea0: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2eb0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2ec0: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2ed0: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2ee0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2ef0: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2f00: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2f10: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2f20: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2f30: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2f40: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2f50: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2f60: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2f70: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2f80: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2f90: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
2fa0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2fb0: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2fc0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2fd0: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
2fe0: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
2ff0: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
3000: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
3010: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
3020: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
3030: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
3040: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3050: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3060: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3070: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3080: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3090: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
30a0: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
30b0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
30c0: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
30d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30e0: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
30f0: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3100: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3110: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3120: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3130: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3140: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
3150: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3160: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3170: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3180: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3190: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
31a0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
31b0: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
31c0: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
31d0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
31e0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
31f0: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3200: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3210: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3220: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3230: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
3240: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
3250: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3260: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3270: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3280: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3290: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
32a0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
32b0: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
32c0: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
32d0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
32e0: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
32f0: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3300: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3310: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3320: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3330: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
3340: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
3350: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3360: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3370: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3380: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3390: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
33a0: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
33b0: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
33c0: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
33d0: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
33e0: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
33f0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3400: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3410: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3420: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
3430: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
3440: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
3450: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3460: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3470: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3480: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3490: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
34a0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
34b0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
34c0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
34d0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
34e0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34f0: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3500: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3510: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
3520: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
3530: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
3540: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
3550: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3560: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3570: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3580: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3590: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
35a0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
35b0: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
35c0: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
35d0: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
35e0: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
35f0: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
3600: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
3610: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
3620: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
3630: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
3640: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
3650: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3660: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3670: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3680: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3690: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
36a0: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
36b0: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
36c0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36d0: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
36e0: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
36f0: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
3700: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3710: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
3720: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
3730: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3740: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
3750: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3760: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3770: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3780: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3790: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
37a0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
37b0: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
37c0: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
37d0: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
37e0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
37f0: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
3800: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
3810: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3820: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
3830: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
3840: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
3850: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3860: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3870: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3880: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3890: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
38a0: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
38b0: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
38c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
38d0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
38e0: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
38f0: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3900: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3910: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3920: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3930: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3940: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3950: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3960: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3970: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3980: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3990: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
39a0: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
39b0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
39c0: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
39d0: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
39e0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
39f0: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3a00: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3a10: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3a20: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3a30: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3a40: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3a50: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3a60: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3a70: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3a80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3a90: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3aa0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3ab0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3ac0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3ad0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ae0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3af0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3b00: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3b10: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3b20: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3b30: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3b40: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3b50: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3b60: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3b70: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3b80: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3b90: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3ba0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3bb0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3bc0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3bd0: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3be0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3bf0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3c00: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3c10: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3c20: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3c30: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3c40: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3c50: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3c60: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3c70: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3c80: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3c90: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3ca0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3cb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3cc0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3cd0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3ce0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3cf0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3d00: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3d10: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3d20: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3d30: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3d40: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3d50: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3d60: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3d70: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3d80: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3d90: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3da0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3db0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3dc0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3dd0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3de0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3df0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3e00: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3e10: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3e20: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3e30: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3e40: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3e50: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3e60: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3e70: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3e80: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3e90: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3ea0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3eb0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3ec0: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3ed0: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3ee0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3ef0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3f00: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3f10: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3f20: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3f30: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3f40: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3f50: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3f60: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3f70: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3f80: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3f90: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
3fa0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3fb0: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
3fc0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3fd0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3fe0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
3ff0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
4000: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4010: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
4020: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4030: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
4040: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
4050: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4060: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4070: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4080: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4090: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
40a0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
40b0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
40c0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
40d0: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
40e0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
40f0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4100: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4110: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4120: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4130: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
4140: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
4150: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4160: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4170: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
41a0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
41b0: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41d0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
41e0: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
41f0: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4200: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4210: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4220: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4230: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
4240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4250: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4260: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4270: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4280: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4290: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
42b0: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
42c0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
42d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
42e0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
42f0: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4300: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4310: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4320: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4330: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
4340: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
4350: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4360: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4370: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4380: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4390: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
43a0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
43b0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
43c0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
43d0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
43e0: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
43f0: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4400: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4410: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4420: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4430: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
4440: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
4450: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4470: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4480: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
4490: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
44a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44b0: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
44c0: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
44d0: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
44e0: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
44f0: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4500: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4510: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4520: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4530: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
4540: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
4550: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
4560: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4570: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4580: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4590: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
45a0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
45b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
45c0: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
45d0: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
45e0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
45f0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4600: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4610: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4620: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
4650: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
4660: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4670: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4690: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
46a0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
46b0: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
46c0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
46d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
46e0: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
46f0: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4700: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4710: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4730: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
4740: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
4750: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
4760: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4770: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4780: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4790: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
47a0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
47b0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
47c0: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
47d0: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
47e0: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
47f0: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4800: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4810: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4820: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4830: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
4840: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4850: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
4860: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4870: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4880: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4890: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
48a0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
48b0: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
48c0: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
48d0: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
48e0: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
48f0: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4900: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4910: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4920: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4930: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4940: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4950: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4960: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4970: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4980: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4990: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
49a0: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
49b0: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
49c0: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
49d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49e0: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
49f0: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4a00: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a20: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4a30: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4a40: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4a50: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4a60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4a70: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4a80: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4a90: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4aa0: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4ab0: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4ac0: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4ad0: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4af0: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4b00: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4b10: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4b20: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4b30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b40: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4b50: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4b60: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4b70: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4b80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4b90: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4ba0: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4bb0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4bc0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4bd0: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4be0: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4bf0: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4c00: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4c10: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4c20: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4c30: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4c40: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4c50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c60: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4c70: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4c80: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4c90: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4ca0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4cb0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4cc0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4cd0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4ce0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4cf0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4d00: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4d10: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4d20: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4d30: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4d40: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4d50: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4d60: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4d70: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4d80: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4d90: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4da0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4db0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4dc0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4dd0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4de0: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4df0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4e00: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4e10: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4e20: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4e30: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4e40: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4e50: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4e60: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74  rsion 3.3.8 [dat
4e70: 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e  eof:3.3.8].** an
4e80: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4e90: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4ea0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4eb0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4ec0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4ed0: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4ee0: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4ef0: 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20  These [extended 
4f00: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72  result codes] ar
4f10: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4f20: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4f30: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4f40: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4f50: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4f60: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4f70: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20  t_codes()] API. 
4f80: 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65   Or, the extende
4f90: 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68  d code for.** th
4fa0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72  e most recent er
4fb0: 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69  ror can be obtai
4fc0: 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
4fd0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
4fe0: 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64  rrcode()]..*/.#d
4ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5000: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
5010: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5020: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
5030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5040: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
5050: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5060: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
5070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5080: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
5090: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50a0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
50b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
50c0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
50d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
50e0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
50f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5100: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
5110: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5120: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5130: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
5140: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
5150: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5160: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
5170: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
5180: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
5190: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
51a0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
51b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
51c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
51d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
51e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
5200: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
5210: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
5220: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5230: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
5240: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5250: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
5260: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5270: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
5280: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
5290: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
52a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52b0: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
52c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
52e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52f0: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
5300: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5310: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
5320: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5330: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
5340: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
5350: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
5360: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5370: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
5380: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5390: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
53a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53b0: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
53c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
53d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
53e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53f0: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
5400: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
5410: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
5420: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5430: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
5440: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
5450: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
5460: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5470: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
5480: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
5490: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
54a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54b0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
54c0: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
54d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
54e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54f0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
5500: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5510: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
5520: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5530: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
5540: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5550: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
5560: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5570: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
5580: 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c  _NOENT      (SQL
5590: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c  ITE_IOERR | (23<
55a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55b0: 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20  ITE_IOERR_MMAP  
55c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
55d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c  ITE_IOERR | (24<
55e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55f0: 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d  ITE_IOERR_GETTEM
5600: 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  PPATH       (SQL
5610: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c  ITE_IOERR | (25<
5620: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5630: 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41  ITE_IOERR_CONVPA
5640: 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TH          (SQL
5650: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c  ITE_IOERR | (26<
5660: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5670: 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20  ITE_IOERR_VNODE 
5680: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5690: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c  ITE_IOERR | (27<
56a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56b0: 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20  ITE_IOERR_AUTH  
56c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
56d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c  ITE_IOERR | (28<
56e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56f0: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
5700: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
5710: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
5720: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5730: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
5740: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
5750: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5760: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5770: 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53  QLITE_BUSY_SNAPS
5780: 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53  HOT           (S
5790: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
57a0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
57b0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
57c0: 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28  NOTEMPDIR      (
57d0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
57e0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
57f0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5800: 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20  N_ISDIR         
5810: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5820: 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  N | (2<<8)).#def
5830: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5840: 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20  PEN_FULLPATH    
5850: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5860: 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  PEN | (3<<8)).#d
5870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5880: 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20  TOPEN_CONVPATH  
5890: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
58a0: 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a  TOPEN | (4<<8)).
58b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
58c0: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
58d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
58e0: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
58f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5900: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5910: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
5920: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
5930: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5940: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
5950: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
5960: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
5970: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5980: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
5990: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
59a0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
59b0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
59c0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44  QLITE_READONLY_D
59d0: 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53  BMOVED        (S
59e0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
59f0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5a10: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5a20: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5a30: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5a40: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a50: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5a60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a70: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a90: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5aa0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ab0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5ac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ad0: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5ae0: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5af0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5b00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5b20: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5b30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5b50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b60: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5b70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b80: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5b90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ba0: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5bb0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bc0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5be0: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5bf0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5c00: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5c10: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5c30: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5c40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c50: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5c60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c70: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5c80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c90: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5cb0: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20  RAINT_ROWID     
5cc0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5cd0: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a  RAINT |(10<<8)).
5ce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5cf0: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41  OTICE_RECOVER_WA
5d00: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e  L      (SQLITE_N
5d10: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a  OTICE | (1<<8)).
5d20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d30: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f  OTICE_RECOVER_RO
5d40: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e  LLBACK (SQLITE_N
5d50: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a  OTICE | (2<<8)).
5d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
5d70: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58  ARNING_AUTOINDEX
5d80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57         (SQLITE_W
5d90: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29  ARNING | (1<<8))
5da0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5db0: 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20  AUTH_USER       
5dc0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5dd0: 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AUTH | (1<<8)).#
5de0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
5df0: 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c  _LOAD_PERMANENTL
5e00: 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b  Y     (SQLITE_OK
5e10: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5e20: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5e30: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5e40: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5e50: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5e60: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5e70: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5e80: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5e90: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5ea0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5eb0: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5ec0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5ed0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5ee0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5ef0: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5f00: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5f10: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5f20: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
5f30: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5f40: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5f50: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5f60: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5f70: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
5f80: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5f90: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5fa0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5fb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5fc0: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
5fd0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5fe0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5ff0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
6000: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
6010: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
6020: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6030: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
6040: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
6050: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
6060: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6070: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
6080: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
6090: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
60a0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60b0: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
60c0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
60d0: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
60e0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
60f0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6100: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
6110: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6120: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
6130: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6140: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6150: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
6160: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
6170: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* 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 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
61a0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
61b0: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
61c0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
61d0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
61e0: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
61f0: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
6200: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6210: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
6220: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6230: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
6240: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6250: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
6260: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6270: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
6280: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6290: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
62a0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
62b0: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
62c0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62d0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
62e0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
62f0: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
6300: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6310: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
6320: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
6330: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
6340: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6350: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6360: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
6370: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
6380: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
6390: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
63a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
63b0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
63c0: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
63d0: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
63e0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
63f0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6400: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
6410: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
6420: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
6430: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6440: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6450: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
6460: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6470: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
6480: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
6490: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
64a0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
64b0: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
64c0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
64d0: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
64e0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
64f0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6500: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
6510: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6520: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
6530: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
6540: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
6550: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6560: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
6570: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
6580: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
6590: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
65a0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
65b0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
65c0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
65d0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
65e0: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
65f0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6600: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
6610: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6620: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6630: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6640: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6650: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6660: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
6670: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
6680: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6690: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
66a0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
66b0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
66c0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
66d0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
66e0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
66f0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6700: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
6710: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6720: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6730: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6740: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6750: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6760: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
6770: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
6780: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6790: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
67a0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
67b0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
67c0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
67d0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
67e0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
67f0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
6800: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
6810: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6820: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
6830: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6840: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
6850: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6860: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
6870: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
6880: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
6890: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
68a0: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
68b0: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
68c0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
68d0: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
68e0: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
68f0: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
6900: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
6910: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6920: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
6930: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
6940: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
6950: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6960: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6970: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
6980: 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65  cate that a file
6990: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
69a0: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
69b0: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
69c0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
69d0: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
69e0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
69f0: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
6a00: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
6a10: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
6a20: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
6a30: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
6a40: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  ileges..*/.#defi
6a50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6a60: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6a70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6a80: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6a90: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6aa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6ab0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6ac0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6ad0: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6ae0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6b00: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6b10: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6b20: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6b30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6b40: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6b50: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6b60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6b70: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6b80: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6b90: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6ba0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6bb0: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6bc0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6be0: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6bf0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6c00: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6c10: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6c20: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6c30: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6c40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6c50: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6c60: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c80: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ca0: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6cb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6cc0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6cd0: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
6ce0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6cf0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6d00: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
6d10: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
6d20: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6d30: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
6d40: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a    0x00002000../*
6d50: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6d60: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6d70: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6d80: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6d90: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6da0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6db0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6dc0: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6dd0: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6de0: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6df0: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6e00: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6e10: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6e20: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6e30: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6e40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6e50: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6e60: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6e70: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6e80: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6e90: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6ea0: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6eb0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6ec0: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6ed0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6ee0: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6ef0: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6f00: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6f10: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6f20: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
6f30: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6f40: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
6f50: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
6f60: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
6f70: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6f80: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
6f90: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
6fa0: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6fb0: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
6fc0: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
6fd0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
6fe0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
6ff0: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
7000: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
7010: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
7020: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
7030: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
7040: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
7050: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
7060: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
7070: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
7080: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
7090: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
70a0: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
70b0: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
70c0: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
70d0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
70e0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
70f0: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
7100: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
7110: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
7120: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
7130: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
7140: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7150: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7160: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
7170: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
7180: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
7190: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
71a0: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
71b0: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
71c0: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
71d0: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
71e0: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
71f0: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
7200: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
7210: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
7220: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
7230: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
7240: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7250: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7260: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
7270: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
7280: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
7290: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
72a0: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
72b0: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
72c0: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
72d0: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
72e0: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
72f0: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
7300: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
7310: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7320: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
7330: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
7340: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
7350: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7360: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7370: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
7380: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
7390: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
73a0: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
73b0: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
73c0: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
73d0: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
73e0: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
73f0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7400: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
7410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7420: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
7430: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
7440: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7450: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
7460: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
7470: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7480: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
7490: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
74a0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
74b0: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
74c0: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
74d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
74e0: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
74f0: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
7500: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
7510: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7520: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
7530: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
7540: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
7550: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
7560: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
7570: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
7580: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
7590: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
75a0: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
75b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
75c0: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
75d0: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
75e0: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
75f0: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
7600: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
7610: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7620: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
7630: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
7640: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
7650: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
7660: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7670: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
7680: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
7690: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
76a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
76b0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
76c0: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
76d0: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
76e0: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
76f0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7700: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7710: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
7720: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7730: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
7740: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
7750: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
7760: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7770: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
7780: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
7790: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
77a0: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
77b0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
77c0: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
77d0: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
77e0: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
77f0: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
7800: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
7810: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7820: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
7830: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
7840: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7850: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
7860: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7870: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
7880: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
7890: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
78a0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
78b0: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
78c0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
78d0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
78e0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
78f0: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
7900: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
7910: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
7920: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
7930: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
7940: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
7950: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7960: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
7970: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7980: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7990: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
79a0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
79b0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
79c0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
79d0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
79e0: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
79f0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7a00: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7a10: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7a20: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
7a30: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7a40: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
7a50: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
7a60: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7a70: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
7a80: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7a90: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7aa0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7ab0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7ac0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7ad0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7ae0: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7af0: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7b00: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7b10: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7b20: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
7b30: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7b40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7b50: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
7b60: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7b70: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
7b80: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7b90: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7ba0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7bb0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7bc0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7bd0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7be0: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7bf0: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7c00: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7c10: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7c20: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7c30: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7c40: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
7c50: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7c60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7c70: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7c80: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7c90: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7ca0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7cb0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7cc0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7cd0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7ce0: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7cf0: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7d00: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7d10: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7d20: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7d30: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7d40: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7d50: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7d60: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7d70: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7d80: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7d90: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7da0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7db0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7dc0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7dd0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7de0: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7df0: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7e00: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7e10: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7e20: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7e30: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7e40: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7e50: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7e60: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7e70: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7e80: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7e90: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7ea0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7eb0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7ec0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7ed0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7ee0: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7ef0: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7f00: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7f10: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7f20: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
7f30: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7f40: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
7f50: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
7f60: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
7f70: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
7f80: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
7f90: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
7fa0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
7fb0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
7fc0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
7fd0: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e  ..** A [file con
7fe0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c  trol opcodes | l
7ff0: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
8000: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
8010: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
8020: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
8030: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
8040: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8050: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
8060: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
8070: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
8080: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
8090: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
80a0: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
80b0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
80c0: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
80d0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
80e0: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
80f0: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
8100: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
8110: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
8120: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
8130: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
8140: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
8150: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
8160: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
8170: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
8180: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
8190: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
81a0: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
81b0: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
81c0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
81d0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
81e0: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
81f0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8200: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
8210: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
8220: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
8230: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
8240: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8250: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8260: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
8270: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8280: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
8290: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
82a0: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
82b0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
82c0: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
82d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
82e0: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
82f0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8300: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
8310: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8320: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <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 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
8350: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8360: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8370: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8380: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
8390: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
83a0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
83b0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
83c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
83d0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
83e0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
83f0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
8400: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
8410: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8420: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
8430: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
8440: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
8450: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
8460: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
8470: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
8480: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8490: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
84a0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
84b0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
84c0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
84d0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
84e0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
84f0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
8500: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
8510: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
8520: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
8530: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
8540: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
8550: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
8560: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
8570: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8580: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8590: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
85a0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
85b0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
85c0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
85d0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
85e0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
85f0: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
8600: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
8610: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
8620: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
8630: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
8640: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
8650: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
8660: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
8670: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8680: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8690: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
86a0: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
86b0: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
86c0: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
86d0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
86e0: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
86f0: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
8700: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
8710: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8720: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8730: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
8740: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
8750: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8760: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8770: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8780: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8790: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
87a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
87b0: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
87c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
87d0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
87e0: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
87f0: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
8800: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8810: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8820: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
8830: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
8840: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8850: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
8860: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
8870: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8880: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8890: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
88a0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
88b0: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
88c0: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
88d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
88e0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
88f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8900: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8910: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
8920: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8930: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
8940: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
8950: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
8960: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
8970: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
8980: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8990: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
89a0: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
89b0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
89c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
89d0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
89e0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
89f0: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
8a00: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
8a10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8a20: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
8a30: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
8a40: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
8a50: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
8a60: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
8a70: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
8a80: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8a90: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8aa0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8ab0: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
8ac0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ad0: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
8ae0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8af0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8b00: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
8b10: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
8b20: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8b30: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8b40: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
8b50: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
8b60: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
8b70: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8b80: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
8b90: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8ba0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8bb0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8bc0: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
8bd0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
8be0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
8bf0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
8c00: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
8c10: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
8c20: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
8c30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
8c40: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8c50: 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f  pcodes} {file co
8c60: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a  ntrol opcode}.**
8c70: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8c80: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
8c90: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
8ca0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8cb0: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
8cc0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8cd0: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
8ce0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
8cf0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
8d00: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
8d10: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8d20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
8d30: 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65  CKSTATE]].** The
8d40: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8d50: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8d60: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8d70: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8d80: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8d90: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8da0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8db0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8dc0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8dd0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
8de0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
8df0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
8e00: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
8e10: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
8e20: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8e30: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8e40: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8e50: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8e60: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8e70: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8e80: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8e90: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
8ea0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
8eb0: 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  and is only avai
8ec0: 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53  lable when the S
8ed0: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f  QLITE_TEST.** co
8ee0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
8ef0: 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
8f00: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8f10: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
8f20: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8f30: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
8f40: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
8f50: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
8f60: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
8f70: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
8f80: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
8f90: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
8fa0: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
8fb0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
8fc0: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
8fd0: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
8fe0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
8ff0: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
9000: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
9010: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
9020: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
9030: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
9040: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
9050: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
9060: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
9070: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
9080: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
9090: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
90a0: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
90b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
90c0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
90d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
90e0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
90f0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9100: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
9110: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
9120: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
9130: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9140: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
9150: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
9160: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
9170: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
9180: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
9190: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
91a0: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
91b0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
91c0: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
91d0: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
91e0: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
91f0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
9200: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
9210: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
9220: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
9230: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
9240: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
9250: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
9260: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
9270: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
9280: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
9290: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
92a0: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
92b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
92c0: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
92d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
92e0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
92f0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9300: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9310: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9320: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9330: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9340: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
9350: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
9360: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f  ction.  See also
9370: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
9380: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e  OURNAL_POINTER].
9390: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
93a0: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
93b0: 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  L_POINTER]].** T
93c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
93d0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
93e0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
93f0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
9400: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
9410: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9420: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
9430: 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c  with the journal
9440: 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a   file (either.**
9450: 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a   the [rollback j
9460: 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b  ournal] or the [
9470: 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d  write-ahead log]
9480: 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ) for a particul
9490: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
94a0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
94b0: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
94c0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
94d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
94e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
94f0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9500: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
9510: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9520: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9530: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9540: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9550: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9560: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9570: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
9580: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
9590: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
95a0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
95b0: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
95c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
95d0: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
95e0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
95f0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9600: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
9610: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9620: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9630: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9640: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9650: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
9660: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
9670: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
9680: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9690: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
96a0: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
96b0: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
96c0: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
96d0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
96e0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
96f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9700: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
9710: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
9720: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
9730: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
9740: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
9750: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
9760: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
9770: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
9780: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
9790: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
97a0: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
97b0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
97c0: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
97d0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
97e0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
97f0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
9800: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
9810: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9820: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9830: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9840: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
9850: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
9860: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9870: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9880: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9890: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
98a0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
98b0: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
98c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
98d0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
98e0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
98f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9900: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
9910: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
9920: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
9930: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
9940: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
9950: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
9960: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
9970: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
9980: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
9990: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
99a0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
99b0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
99c0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
99d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
99e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
99f0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9a00: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9a10: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
9a20: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
9a30: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9a40: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9a50: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9a60: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9a70: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9a80: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
9a90: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9aa0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9ab0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
9ac0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
9ad0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
9ae0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
9af0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
9b00: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9b10: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9b20: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9b30: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9b40: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9b50: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
9b60: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
9b70: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
9b80: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
9b90: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
9ba0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
9bb0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
9bc0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
9bd0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
9be0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
9bf0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
9c00: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9c10: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9c20: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9c30: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9c40: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9c50: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
9c60: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
9c70: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
9c80: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
9c90: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
9ca0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
9cb0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
9cc0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
9cd0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
9ce0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
9cf0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
9d00: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9d10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9d20: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9d30: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9d40: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9d50: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
9d60: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
9d70: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
9d80: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
9d90: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
9da0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
9db0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
9dc0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
9dd0: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
9de0: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
9df0: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
9e00: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9e10: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9e20: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9e30: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9e40: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
9e50: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
9e60: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
9e70: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
9e80: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
9e90: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
9ea0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
9eb0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
9ec0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9ed0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
9ee0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9ef0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9f00: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9f10: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9f20: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9f30: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
9f40: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
9f50: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
9f60: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
9f70: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
9f80: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
9f90: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
9fa0: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
9fb0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
9fc0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
9fd0: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
9fe0: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
9ff0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
a000: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
a010: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
a020: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
a030: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
a040: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
a050: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
a060: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
a070: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
a080: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
a090: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
a0a0: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
a0b0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
a0c0: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
a0d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
a0e0: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
a0f0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a100: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
a110: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
a120: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
a130: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
a140: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
a150: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
a160: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a170: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a180: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a190: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a1a0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a1b0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a1c0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a1d0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a1e0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
a1f0: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
a200: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
a210: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
a220: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
a230: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
a240: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
a250: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
a260: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
a270: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
a280: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a290: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
a2a0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
a2b0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a2c0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a2d0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
a2e0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
a2f0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
a300: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
a310: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
a320: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
a330: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
a340: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
a350: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
a360: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a370: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
a380: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
a390: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
a3a0: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
a3b0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a3c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a3d0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a3e0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a3f0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a400: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a410: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a420: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
a430: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
a440: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
a450: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
a460: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
a470: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
a480: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
a490: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
a4a0: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
a4b0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
a4c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a4d0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
a4e0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a4f0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a500: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
a510: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
a520: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
a530: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
a540: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
a550: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
a560: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
a570: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
a580: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
a590: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
a5a0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
a5b0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
a5c0: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
a5d0: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
a5e0: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
a5f0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a600: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a610: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
a620: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a630: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
a640: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
a650: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
a660: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
a670: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
a680: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
a690: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
a6a0: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
a6b0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
a6c0: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
a6d0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a6e0: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
a6f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
a700: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
a710: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
a720: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
a730: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
a740: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
a750: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a760: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
a770: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
a780: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
a790: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
a7a0: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
a7b0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
a7c0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
a7d0: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
a7e0: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
a7f0: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
a800: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
a810: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
a820: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
a830: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a840: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
a850: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
a860: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a870: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
a880: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
a890: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
a8a0: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
a8b0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
a8c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a8d0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
a8e0: 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NTER]].** ^The [
a8f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a900: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
a910: 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72   finds a pointer
a920: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
a930: 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72  l.** [VFSes] cur
a940: 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20  rently in use.  
a950: 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58  ^(The argument X
a960: 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66   in.** sqlite3_f
a970: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53  ile_control(db,S
a980: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
a990: 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20  POINTER,X) must 
a9a0: 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b  be.** of type "[
a9b0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22  sqlite3_vfs] **"
a9c0: 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20  .  This opcodes 
a9d0: 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74  will set *X.** t
a9e0: 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  o a pointer to t
a9f0: 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53  he top-level VFS
aa00: 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  .)^.** ^When the
aa10: 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20  re are multiple 
aa20: 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65  VFS shims in the
aa30: 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63   stack, this opc
aa40: 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a  ode finds the.**
aa50: 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d   upper-most shim
aa60: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
aa70: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aa80: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
aa90: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
aaa0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
aab0: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
aac0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
aad0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
aae0: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
aaf0: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
ab00: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
ab10: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
ab20: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
ab30: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
ab40: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
ab50: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
ab60: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
ab70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ab80: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
ab90: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
aba0: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
abb0: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
abc0: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
abd0: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
abe0: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
abf0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
ac00: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
ac10: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
ac20: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
ac30: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
ac40: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
ac50: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
ac60: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
ac70: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
ac80: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ac90: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
aca0: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
acb0: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
acc0: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
acd0: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
ace0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
acf0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
ad00: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
ad10: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
ad20: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
ad30: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
ad40: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
ad50: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
ad60: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
ad70: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
ad80: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
ad90: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
ada0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
adb0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
adc0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
add0: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
ade0: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
adf0: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
ae00: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
ae10: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
ae20: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
ae30: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
ae40: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
ae50: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
ae60: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
ae70: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
ae80: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
ae90: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
aea0: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
aeb0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
aec0: 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72  nt if result str
aed0: 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20  ing is NULL, or 
aee0: 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63  that returns a c
aef0: 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  opy.** of the re
af00: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74  sult string if t
af10: 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e  he string is non
af20: 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68  -NULL..** ^If th
af30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
af40: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
af50: 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20  trol returns.** 
af60: 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  any result code 
af70: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
af80: 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54  TE_OK] or [SQLIT
af90: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61  E_NOTFOUND], tha
afa0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  t means.** that 
afb0: 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65  the VFS encounte
afc0: 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69  red an error whi
afd0: 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20  le handling the 
afe0: 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65  [PRAGMA] and the
aff0: 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  .** compilation 
b000: 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61  of the PRAGMA fa
b010: 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ils with an erro
b020: 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  r.  ^The [SQLITE
b030: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
b040: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  * file control o
b050: 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67  ccurs at the beg
b060: 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61  inning of pragma
b070: 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79   statement analy
b080: 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74  sis and so.** it
b090: 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72   is able to over
b0a0: 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50  ride built-in [P
b0b0: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
b0c0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
b0d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
b0e0: 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68  HANDLER]].** ^Th
b0f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b100: 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20  BUSYHANDLER].** 
b110: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79  file-control may
b120: 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   be invoked by S
b130: 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74  QLite on the dat
b140: 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c  abase file handl
b150: 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74  e.** shortly aft
b160: 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20  er it is opened 
b170: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
b180: 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53  ide a custom VFS
b190: 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20   with access.** 
b1a0: 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  to the connectio
b1b0: 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  ns busy-handler 
b1c0: 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72  callback. The ar
b1d0: 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70  gument is of typ
b1e0: 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d  e (void **).** -
b1f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
b200: 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73   (void *) values
b210: 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69  . The first (voi
b220: 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f  d *) actually po
b230: 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e  ints.** to a fun
b240: 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69  ction of type (i
b250: 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e  nt (*)(void *)).
b260: 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76   In order to inv
b270: 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  oke the connecti
b280: 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64  ons.** busy-hand
b290: 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ler, this functi
b2a0: 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76  on should be inv
b2b0: 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65  oked with the se
b2c0: 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e  cond (void *) in
b2d0: 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73  .** the array as
b2e0: 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65   the only argume
b2f0: 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  nt. If it return
b300: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
b310: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
b320: 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72  * should be retr
b330: 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72  ied. If it retur
b340: 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73  ns zero, the cus
b350: 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61  tom VFS should a
b360: 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75  bandon the.** cu
b370: 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e  rrent operation.
b380: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b390: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
b3a0: 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70  LENAME]].** ^App
b3b0: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76  lication can inv
b3c0: 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  oke the [SQLITE_
b3d0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
b3e0: 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  ME] file-control
b3f0: 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69  .** to have SQLi
b400: 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a  te generate a.**
b410: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
b420: 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ame using the sa
b430: 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61  me algorithm tha
b440: 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f  t is followed to
b450: 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d   generate.** tem
b460: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73  porary filenames
b470: 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73   for TEMP tables
b480: 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72   and other inter
b490: 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a  nal uses.  The.*
b4a0: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
b4b0: 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68  d be a char** wh
b4c0: 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c  ich will be fill
b4d0: 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65  ed with the file
b4e0: 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20  name.** written 
b4f0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
b500: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
b510: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
b520: 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64  he caller should
b530: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  .** invoke [sqli
b540: 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74  te3_free()] on t
b550: 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f  he result to avo
b560: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  id a memory leak
b570: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b580: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
b590: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
b5a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b5b0: 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
b5c0: 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71  rol is used to q
b5d0: 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a  uery or set the.
b5e0: 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ** maximum numbe
b5f0: 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20  r of bytes that 
b600: 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72  will be used for
b610: 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49   memory-mapped I
b620: 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  /O..** The argum
b630: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
b640: 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74   to a value of t
b650: 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ype sqlite3_int6
b660: 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20  4 that.** is an 
b670: 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d  advisory maximum
b680: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b690: 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20   in the file to 
b6a0: 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65  memory map.  The
b6b0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f  .** pointer is o
b6c0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
b6d0: 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20  the old value.  
b6e0: 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  The limit is not
b6f0: 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74   changed if.** t
b700: 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61  he value origina
b710: 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69  lly pointed to i
b720: 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20  s negative, and 
b730: 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c  so the current l
b740: 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20  imit .** can be 
b750: 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69  queried by passi
b760: 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20  ng in a pointer 
b770: 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  to a negative nu
b780: 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66  mber.  This.** f
b790: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile-control is u
b7a0: 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
b7b0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41  o implement [PRA
b7c0: 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a  GMA mmap_size]..
b7d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b7e0: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d  TE_FCNTL_TRACE]]
b7f0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b800: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c  FCNTL_TRACE] fil
b810: 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64  e control provid
b820: 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f  es advisory info
b830: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68  rmation.** to th
b840: 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74  e VFS about what
b850: 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65   the higher laye
b860: 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  rs of the SQLite
b870: 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67   stack are doing
b880: 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63  ..** This file c
b890: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62  ontrol is used b
b8a0: 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76  y some VFS activ
b8b0: 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69  ity tracing [shi
b8c0: 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ms]..** The argu
b8d0: 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74  ment is a zero-t
b8e0: 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
b8f0: 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73  .  Higher layers
b900: 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74   in the.** SQLit
b910: 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65  e stack may gene
b920: 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f  rate instances o
b930: 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  f this file cont
b940: 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53  rol if.** the [S
b950: 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f  QLITE_USE_FCNTL_
b960: 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  TRACE] compile-t
b970: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
b980: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  abled..**.** <li
b990: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b9a0: 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54  HAS_MOVED]].** T
b9b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b9c0: 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65  _HAS_MOVED] file
b9d0: 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72   control interpr
b9e0: 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74  ets its argument
b9f0: 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   as a.** pointer
ba00: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61   to an integer a
ba10: 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62  nd it writes a b
ba20: 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74  oolean into that
ba30: 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69   integer dependi
ba40: 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  ng.** on whether
ba50: 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65   or not the file
ba60: 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65   has been rename
ba70: 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c  d, moved, or del
ba80: 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a  eted since it.**
ba90: 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65   was first opene
baa0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
bab0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
bac0: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a  2_GET_HANDLE]].*
bad0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bae0: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
baf0: 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NDLE] opcode can
bb00: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
bb10: 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  in the.** underl
bb20: 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65  ying native file
bb30: 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74   handle associat
bb40: 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20 68  ed with a file h
bb50: 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c  andle.  This fil
bb60: 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  e.** control int
bb70: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
bb80: 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65  ment as a pointe
bb90: 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69  r to a native fi
bba0: 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a  le handle and.**
bbb0: 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75   writes the resu
bbc0: 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72  lting value ther
bbd0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
bbe0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
bbf0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a  2_SET_HANDLE]].*
bc00: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bc10: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
bc20: 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  NDLE] opcode is 
bc30: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
bc40: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
bc50: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
bc60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
bc70: 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66  od to swap the f
bc80: 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20  ile handle with 
bc90: 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74  the one.** point
bca0: 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72  ed to by the pAr
bcb0: 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69  g argument.  Thi
bcc0: 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20  s capability is 
bcd0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
bce0: 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20  ing.** and only 
bcf0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
bd00: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
bd10: 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65  E_TEST is define
bd20: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
bd30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
bd40: 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b  BLOCK]].** The [
bd50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
bd60: 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67  _BLOCK] is a sig
bd70: 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c  nal to the VFS l
bd80: 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67  ayer that it mig
bd90: 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61  ht.** be advanta
bda0: 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f  geous to block o
bdb0: 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c  n the next WAL l
bdc0: 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20  ock if the lock 
bdd0: 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65  is not immediate
bde0: 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e  ly.** available.
bdf0: 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73    The WAL subsys
be00: 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20  tem issues this 
be10: 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61  signal during ra
be20: 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e  re.** circumstan
be30: 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ces in order to 
be40: 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69  fix a problem wi
be50: 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65  th priority inve
be60: 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63  rsion..** Applic
be70: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65  ations should <e
be80: 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74  m>not</em> use t
be90: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
bea0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
beb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
bec0: 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  S]].** The [SQLI
bed0: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
bee0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
bef0: 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73  mented by zipvfs
bf00: 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72   only. All other
bf10: 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72  .** VFS should r
bf20: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54  eturn SQLITE_NOT
bf30: 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f  FOUND for this o
bf40: 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pcode..**.** <li
bf50: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bf60: 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  RBU]].** The [SQ
bf70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20  LITE_FCNTL_RBU] 
bf80: 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d  opcode is implem
bf90: 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70 65  ented by the spe
bfa0: 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62 79  cial VFS used by
bfb0: 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74 65  .** the RBU exte
bfc0: 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c  nsion only.  All
bfd0: 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c   other VFS shoul
bfe0: 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  d return SQLITE_
bff0: 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20  NOTFOUND for.** 
c000: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a  this opcode.  .*
c010: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
c020: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c030: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
c040: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
c050: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47  e SQLITE_FCNTL_G
c060: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c070: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
c080: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
c090: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c0a0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
c0b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
c0c0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
c0d0: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
c0e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
c0f0: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
c100: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
c110: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
c120: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
c130: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
c140: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
c150: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
c160: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
c170: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
c180: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
c190: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
c1a0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
c1b0: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
c1c0: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
c1d0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
c1e0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
c1f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c200: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
c210: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
c220: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c230: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
c240: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
c250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c260: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
c270: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
c280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c290: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
c2a0: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
c2b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c2c0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
c2d0: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
c2e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c2f0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
c300: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
c310: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c320: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
c330: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
c340: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
c350: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
c360: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
c370: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
c380: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
c390: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
c3a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
c3b0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
c3c0: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
c3d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c3e0: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
c3f0: 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51     22.#define SQ
c400: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c410: 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _SET_HANDLE     
c420: 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    23.#define SQL
c430: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
c440: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
c450: 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   24.#define SQLI
c460: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20  TE_FCNTL_ZIPVFS 
c470: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c480: 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  25.#define SQLIT
c490: 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20  E_FCNTL_RBU     
c4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
c4b0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
c4c0: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
c4d0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37  ER            27
c4e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c4f0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
c500: 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a  INTER        28.
c510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c520: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c530: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23  ANDLE       29.#
c540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c550: 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20  NTL_PDB         
c560: 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 0a 2f             30../
c570: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d  * deprecated nam
c580: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
c590: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
c5a0: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c5b0: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
c5c0: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c5d0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
c5e0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c5f0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
c600: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
c610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
c620: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
c630: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c640: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a  TL_LAST_ERRNO...
c650: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c660: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
c670: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
c680: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
c690: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
c6a0: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
c6b0: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
c6c0: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
c6d0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
c6e0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
c6f0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
c700: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
c710: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
c720: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
c730: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
c740: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
c750: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
c760: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
c770: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
c780: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
c790: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
c7a0: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
c7b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c7c0: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
c7d0: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
c7e0: 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45  3REF: Loadable E
c7f0: 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a  xtension Thunk.*
c800: 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
c810: 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c  o the opaque sql
c820: 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65  ite3_api_routine
c830: 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 70  s structure is p
c840: 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20  assed as.** the 
c850: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
c860: 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20  to entry points 
c870: 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74  of [loadable ext
c880: 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a  ensions].  This.
c890: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  ** structure mus
c8a0: 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20 69  t be typedefed i
c8b0: 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20  n order to work 
c8c0: 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20  around compiler 
c8d0: 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73  warnings.** on s
c8e0: 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  ome platforms..*
c8f0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
c900: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
c910: 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70  tines sqlite3_ap
c920: 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a  i_routines;../*.
c930: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
c940: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
c950: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
c960: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
c970: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
c980: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
c990: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
c9a0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
c9b0: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
c9c0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
c9d0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
c9e0: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
c9f0: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
ca00: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
ca10: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
ca20: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
ca30: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
ca40: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
ca50: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
ca60: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
ca70: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
ca80: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
ca90: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
caa0: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
cab0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
cac0: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
cad0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
cae0: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
caf0: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
cb00: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
cb10: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
cb20: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
cb30: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
cb40: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
cb50: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
cb60: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
cb70: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
cb80: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
cb90: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
cba0: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
cbb0: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
cbc0: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
cbd0: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
cbe0: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
cbf0: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
cc00: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
cc10: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
cc20: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
cc30: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
cc40: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
cc50: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
cc60: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
cc70: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
cc80: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
cc90: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
cca0: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
ccb0: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
ccc0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
ccd0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
cce0: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
ccf0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
cd00: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
cd10: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
cd20: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
cd30: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
cd40: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
cd50: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
cd60: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
cd70: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
cd80: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
cd90: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
cda0: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
cdb0: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
cdc0: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
cdd0: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
cde0: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
cdf0: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
ce00: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
ce10: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
ce20: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
ce30: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
ce40: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
ce50: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
ce60: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
ce70: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
ce80: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
ce90: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
cea0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
ceb0: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
cec0: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
ced0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
cee0: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
cef0: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
cf00: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
cf10: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
cf20: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
cf30: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
cf40: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
cf50: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
cf60: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
cf70: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
cf80: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
cf90: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
cfa0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
cfb0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
cfc0: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
cfd0: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
cfe0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
cff0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
d000: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
d010: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
d020: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
d030: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
d040: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
d050: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
d060: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
d070: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
d080: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
d090: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
d0a0: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
d0b0: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
d0c0: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
d0d0: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
d0e0: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
d0f0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
d100: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
d110: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
d120: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
d130: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
d140: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
d150: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
d160: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
d170: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
d180: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
d190: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
d1a0: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
d1b0: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
d1c0: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
d1d0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
d1e0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
d1f0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
d200: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
d210: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
d220: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
d230: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
d240: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
d250: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
d260: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
d270: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d280: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
d290: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
d2a0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
d2b0: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
d2c0: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
d2d0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d2e0: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
d2f0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d300: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
d310: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
d320: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
d330: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
d340: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
d350: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
d360: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
d370: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
d380: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
d390: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
d3a0: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
d3b0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
d3c0: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
d3d0: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
d3e0: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
d3f0: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
d400: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
d410: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
d420: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
d430: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
d440: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
d450: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
d460: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
d470: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
d480: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
d490: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
d4a0: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
d4b0: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
d4c0: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
d4d0: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
d4e0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
d4f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d500: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
d510: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
d520: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
d530: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d540: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
d550: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d560: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
d570: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d580: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
d590: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d5a0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
d5b0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d5c0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
d5d0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
d5e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d5f0: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
d600: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
d610: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
d620: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
d630: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
d640: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
d650: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
d660: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
d670: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
d680: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
d690: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
d6a0: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
d6b0: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
d6c0: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
d6d0: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
d6e0: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
d6f0: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
d700: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
d710: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
d720: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
d730: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
d740: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
d750: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
d760: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
d770: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
d780: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
d790: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
d7a0: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
d7b0: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
d7c0: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
d7d0: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
d7e0: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
d7f0: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
d800: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
d810: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
d820: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
d830: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
d840: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
d850: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
d860: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
d870: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
d880: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
d890: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
d8a0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
d8b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
d8c0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d8d0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
d8e0: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
d8f0: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
d900: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
d910: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
d920: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
d930: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
d940: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
d950: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
d960: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
d970: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
d980: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
d990: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
d9a0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
d9b0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
d9c0: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
d9d0: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
d9e0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
d9f0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
da00: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
da10: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
da20: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
da30: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
da40: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
da50: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
da60: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
da70: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
da80: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
da90: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
daa0: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
dab0: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
dac0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
dad0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
dae0: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
daf0: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
db00: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
db10: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
db20: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
db30: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
db40: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
db50: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
db60: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
db70: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
db80: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
db90: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
dba0: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
dbb0: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
dbc0: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
dbd0: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
dbe0: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
dbf0: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
dc00: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
dc10: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
dc20: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
dc30: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
dc40: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
dc50: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
dc60: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
dc70: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
dc80: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
dc90: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
dca0: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
dcb0: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
dcc0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
dcd0: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
dce0: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
dcf0: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
dd00: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
dd10: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
dd20: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
dd30: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
dd40: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
dd50: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
dd60: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
dd70: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
dd80: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
dd90: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
dda0: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
ddb0: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
ddc0: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
ddd0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
dde0: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
ddf0: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
de00: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
de10: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
de20: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
de30: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
de40: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
de50: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
de60: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
de70: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
de80: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
de90: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
dea0: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
deb0: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
dec0: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
ded0: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
dee0: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
def0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
df00: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
df10: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
df20: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
df30: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
df40: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
df50: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
df60: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
df70: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
df80: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
df90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
dfa0: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
dfb0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
dfc0: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
dfd0: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
dfe0: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
dff0: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
e000: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
e010: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
e020: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
e030: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
e040: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
e050: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
e060: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
e070: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
e080: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
e090: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
e0a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
e0b0: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
e0c0: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
e0d0: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
e0e0: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
e0f0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
e100: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
e110: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
e120: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
e130: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
e140: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
e150: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
e160: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
e170: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
e180: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
e190: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
e1a0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
e1b0: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
e1c0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
e1d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
e1e0: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
e1f0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
e200: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
e210: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
e220: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
e230: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
e240: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
e250: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
e260: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
e270: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
e280: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
e290: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
e2a0: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
e2b0: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
e2c0: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
e2d0: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
e2e0: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
e2f0: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
e300: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e310: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
e320: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
e330: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
e340: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
e350: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
e360: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
e370: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
e380: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
e390: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
e3a0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
e3b0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e3c0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
e3d0: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
e3e0: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
e3f0: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
e400: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
e410: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
e420: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
e430: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
e440: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
e450: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
e460: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
e470: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
e480: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
e490: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
e4a0: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
e4b0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
e4c0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
e4d0: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
e4e0: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
e4f0: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
e500: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
e510: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
e520: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
e530: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
e540: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
e550: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
e560: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
e570: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
e580: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
e590: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
e5a0: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
e5b0: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
e5c0: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
e5d0: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
e5e0: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
e5f0: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
e600: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
e610: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
e620: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
e630: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
e640: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
e650: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
e660: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
e670: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
e680: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
e690: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
e6a0: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
e6b0: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
e6c0: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
e6d0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e6e0: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
e6f0: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
e700: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
e710: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
e720: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
e730: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
e740: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
e750: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
e760: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
e770: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
e780: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
e790: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
e7a0: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
e7b0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
e7c0: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
e7d0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e7e0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
e7f0: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
e800: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
e810: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
e820: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
e830: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
e840: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
e850: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
e860: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
e870: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
e880: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
e890: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
e8a0: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
e8b0: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
e8c0: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
e8d0: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
e8e0: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
e8f0: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
e900: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
e910: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
e920: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
e930: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
e940: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
e950: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
e960: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
e970: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
e980: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
e990: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
e9a0: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
e9b0: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
e9c0: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
e9d0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e9e0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
e9f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
ea00: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
ea10: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
ea20: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
ea30: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
ea40: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ea50: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
ea60: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
ea70: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
ea80: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ea90: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
eaa0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
eab0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
eac0: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
ead0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eae0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
eaf0: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
eb00: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
eb10: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
eb20: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
eb30: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
eb40: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
eb50: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
eb60: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
eb70: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
eb80: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
eb90: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
eba0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
ebb0: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
ebc0: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
ebd0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
ebe0: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
ebf0: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
ec00: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
ec10: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
ec20: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
ec30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ec40: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
ec50: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
ec60: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
ec70: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
ec80: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
ec90: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
eca0: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
ecb0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
ecc0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
ecd0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
ece0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
ecf0: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
ed00: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
ed10: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
ed20: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
ed30: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
ed40: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
ed50: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
ed60: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
ed70: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
ed80: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
ed90: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
eda0: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
edb0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
edc0: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
edd0: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
ede0: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
edf0: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
ee00: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
ee10: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
ee20: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ee30: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
ee40: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
ee50: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
ee60: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
ee70: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
ee80: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ee90: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
eea0: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
eeb0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
eec0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
eed0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
eee0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
eef0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
ef00: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
ef10: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
ef20: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
ef30: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
ef40: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
ef50: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  future versions.
ef60: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
ef70: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
ef80: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
ef90: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
efa0: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
efb0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
efc0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
efd0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
efe0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
eff0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
f000: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
f010: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
f020: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
f030: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
f040: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
f050: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
f060: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
f070: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
f080: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
f090: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
f0a0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
f0b0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
f0c0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f0d0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
f0e0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
f0f0: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
f100: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
f110: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
f120: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
f130: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
f140: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
f150: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
f160: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
f170: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
f180: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
f190: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
f1a0: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
f1b0: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
f1c0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
f1d0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
f1e0: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
f1f0: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
f200: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
f210: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
f220: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
f230: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
f240: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
f250: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
f260: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
f270: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
f280: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
f290: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
f2a0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
f2b0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
f2c0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
f2d0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
f2e0: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
f2f0: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
f300: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
f310: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
f320: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
f330: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
f340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f350: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
f360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f370: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
f380: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
f390: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
f3a0: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
f3b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f3c0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
f3d0: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
f3e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
f3f0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
f400: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
f410: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
f420: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
f430: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
f440: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
f450: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
f460: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
f470: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
f480: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
f490: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
f4a0: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
f4b0: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
f4c0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
f4d0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
f4e0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f4f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f500: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
f510: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f520: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f530: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
f540: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
f550: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f560: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f570: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
f580: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
f590: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
f5a0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f5b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
f5c0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
f5d0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
f5e0: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
f5f0: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
f600: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
f610: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
f620: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
f630: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f640: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
f650: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
f660: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
f670: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
f680: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
f690: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
f6a0: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
f6b0: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
f6c0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
f6d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f6e0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
f6f0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
f700: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
f710: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
f720: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f730: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
f740: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
f750: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
f760: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
f770: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
f780: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
f790: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
f7a0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f7b0: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
f7c0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
f7d0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
f7e0: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
f7f0: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
f800: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
f810: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
f820: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
f830: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
f840: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
f850: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
f860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f870: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
f880: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
f890: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
f8a0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
f8b0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f8c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f8d0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
f8e0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
f8f0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
f900: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
f910: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
f920: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
f930: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
f940: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
f950: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f960: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
f970: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
f980: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
f990: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
f9a0: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
f9b0: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
f9c0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
f9d0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
f9e0: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
f9f0: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
fa00: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
fa10: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
fa20: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
fa30: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
fa40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fa50: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
fa60: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
fa70: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
fa80: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
fa90: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
faa0: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
fab0: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
fac0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
fad0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
fae0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
faf0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
fb00: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
fb10: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
fb20: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fb30: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
fb40: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
fb50: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
fb60: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
fb70: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
fb80: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
fb90: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
fba0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
fbb0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
fbc0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
fbd0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
fbe0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
fbf0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
fc00: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
fc10: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
fc20: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
fc30: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
fc40: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
fc50: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
fc60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
fc70: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
fc80: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
fc90: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
fca0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
fcb0: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
fcc0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
fcd0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fce0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fcf0: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
fd00: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
fd10: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
fd20: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
fd30: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fd40: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
fd50: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
fd60: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
fd70: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
fd80: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
fd90: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
fda0: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
fdb0: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
fdc0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
fdd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
fde0: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
fdf0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
fe00: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
fe10: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
fe20: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
fe30: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
fe40: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
fe50: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
fe60: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
fe70: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
fe80: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
fe90: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
fea0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
feb0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
fec0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
fed0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
fee0: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
fef0: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
ff00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ff10: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
ff20: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
ff30: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
ff40: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
ff50: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
ff60: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
ff70: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
ff80: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
ff90: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
ffa0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
ffb0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
ffc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ffd0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
ffe0: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
fff0: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
10000 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10010 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
10020 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
10030 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
10040 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
10050 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10060 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
10070 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
10080 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
10090 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
100a0 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
100b0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
100c0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
100d0 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
100e0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
100f0 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
10100 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
10110 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
10120 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
10130 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
10140 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10150 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
10160 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
10170 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
10180 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
10190 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
101a0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
101b0 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
101c0 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
101d0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
101e0 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
101f0 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
10200 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
10210 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
10220 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
10230 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
10240 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
10250 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
10260 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
10270 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
10280 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10290 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
102a0 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
102b0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
102c0 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
102d0 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
102e0 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
102f0 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
10300 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
10310 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
10320 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
10330 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10340 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
10350 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
10360 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
10370 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
10380 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
10390 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
103a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
103b0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
103c0 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
103d0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
103e0 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
103f0 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
10400 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
10410 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10420 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
10430 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
10440 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
10450 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
10460 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
10470 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
10480 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
10490 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
104a0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
104b0 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
104c0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
104d0 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
104e0 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
104f0 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
10500 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
10510 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
10520 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
10530 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
10540 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10550 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
10560 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
10570 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
10580 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
10590 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
105a0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
105b0 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
105c0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
105d0 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
105e0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
105f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
10600 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
10610 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10620 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
10630 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
10640 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
10650 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
10660 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
10670 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
10680 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
10690 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
106a0 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
106b0 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
106c0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
106d0 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
106e0 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
106f0 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
10700 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
10710 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
10720 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
10730 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
10740 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
10750 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
10760 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
10770 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
10780 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
10790 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
107a0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
107b0 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
107c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
107d0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
107e0 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
107f0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
10800 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
10810 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
10820 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
10830 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
10840 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
10850 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
10860 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
10870 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
10880 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
10890 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
108a0 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
108b0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
108c0 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
108d0 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
108e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
108f0 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
10900 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
10910 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
10920 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
10930 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
10940 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
10950 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10960 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
10970 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
10980 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
10990 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
109a0 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
109b0 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
109c0 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
109d0 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
109e0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
109f0 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
10a00 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
10a10 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
10a20 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
10a30 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
10a40 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
10a50 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
10a60 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
10a70 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
10a80 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
10a90 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
10aa0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71  .**.** <b>The sq
10ab0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10ac0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
10ad0 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 20  threadsafe. The 
10ae0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
10af0 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20  ust ensure that 
10b00 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
10b10 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
10b20 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
10b30 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
10b40 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10b50 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62  ) is running.</b
10b60 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
10b70 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10b80 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e  erface.** may on
10b90 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
10ba0 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
10bb0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
10bc0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
10bd0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
10be0 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
10bf0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
10c00 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
10c10 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10c20 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
10c30 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
10c40 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
10c50 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
10c60 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
10c70 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
10c80 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
10c90 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
10ca0 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
10cb0 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
10cc0 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
10cd0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
10ce0 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
10cf0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
10d00 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
10d10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
10d20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10d30 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10d40 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
10d50 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
10d60 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
10d70 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
10d80 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
10d90 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
10da0 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
10db0 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
10dc0 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
10dd0 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
10de0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
10df0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
10e00 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
10e10 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
10e20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
10e30 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
10e40 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
10e50 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
10e60 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
10e70 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
10e80 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
10e90 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
10ea0 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
10eb0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
10ec0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
10ed0 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
10ee0 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
10ef0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
10f00 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
10f10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10f20 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
10f30 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
10f40 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
10f50 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
10f60 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
10f70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10f80 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
10f90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10fa0 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
10fb0 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
10fc0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10fd0 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
10fe0 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
10ff0 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
11000 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
11010 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
11020 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
11030 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
11040 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
11050 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11060 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
11070 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
11080 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
11090 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
110a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
110b0 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
110c0 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
110d0 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
110e0 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
110f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11100 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
11110 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
11120 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
11130 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
11140 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
11150 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
11160 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
11170 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
11180 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
11190 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
111a0 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
111b0 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
111c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
111d0 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
111e0 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
111f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11200 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
11210 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
11220 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
11230 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
11240 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
11250 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
11260 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
11270 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
11280 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
11290 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
112a0 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
112b0 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
112c0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
112d0 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
112e0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
112f0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11300 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
11310 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11320 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
11330 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
11340 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
11350 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11360 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
11370 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
11380 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
11390 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
113a0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
113b0 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
113c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
113d0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
113e0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
113f0 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
11400 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
11410 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
11420 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
11430 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
11440 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
11450 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
11460 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
11470 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
11480 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
11490 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
114a0 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
114b0 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
114c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
114d0 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
114e0 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
114f0 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
11500 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
11510 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
11520 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
11530 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
11540 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
11550 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
11560 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
11570 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
11580 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11590 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
115a0 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
115b0 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
115c0 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
115d0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
115e0 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
115f0 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
11600 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
11610 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
11620 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
11630 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
11640 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
11650 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
11660 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
11670 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
11680 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
11690 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
116a0 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
116b0 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
116c0 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
116d0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
116e0 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
116f0 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
11700 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
11710 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
11720 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
11730 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11740 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
11750 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
11760 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
11770 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
11780 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
11790 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
117a0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
117b0 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
117c0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
117d0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
117e0 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
117f0 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
11800 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
11810 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
11820 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
11830 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
11840 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
11850 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
11860 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
11870 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
11880 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
11890 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
118a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
118b0 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
118c0 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
118d0 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
118e0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
118f0 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
11900 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
11910 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
11920 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
11930 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
11940 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
11950 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
11960 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
11970 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
11980 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11990 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
119a0 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
119b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
119c0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
119d0 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
119e0 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
119f0 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
11a00 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
11a10 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
11a20 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
11a30 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
11a40 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
11a50 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
11a60 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
11a70 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f  y allocator.  Fo
11a80 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
11a90 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
11aa0 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
11ab0 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
11ac0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
11ad0 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
11ae0 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
11af0 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
11b00 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
11b10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
11b20 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
11b30 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
11b40 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
11b50 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
11b60 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
11b70 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
11b80 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
11b90 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
11ba0 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
11bb0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
11bc0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
11bd0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
11be0 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
11bf0 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
11c00 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
11c10 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
11c20 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
11c30 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
11c40 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
11c50 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
11c60 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
11c70 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
11c80 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
11c90 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
11ca0 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
11cb0 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
11cc0 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
11cd0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
11ce0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
11cf0 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
11d00 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
11d10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11d20 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
11d30 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
11d40 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
11d50 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
11d60 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
11d70 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
11d80 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
11d90 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
11da0 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
11db0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
11dc0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
11dd0 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
11de0 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
11df0 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
11e00 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
11e10 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
11e20 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
11e30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
11e40 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
11e50 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
11e60 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
11e70 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
11e80 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
11e90 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
11ea0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
11eb0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
11ec0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11ed0 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
11ee0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
11ef0 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
11f00 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11f10 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
11f20 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
11f30 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
11f40 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
11f50 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
11f60 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
11f70 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
11f80 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
11f90 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
11fa0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11fb0 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
11fc0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
11fd0 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
11fe0 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
11ff0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
12000 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
12010 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
12020 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
12030 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
12040 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
12050 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
12060 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
12070 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
12080 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
12090 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
120a0 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
120b0 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
120c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
120d0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
120e0 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
120f0 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
12100 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
12110 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
12120 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12130 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
12140 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
12150 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
12160 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
12170 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
12180 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
12190 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
121a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
121b0 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
121c0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
121d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
121e0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
121f0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
12200 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
12210 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12220 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
12230 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
12240 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
12250 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
12260 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
12270 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
12280 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
12290 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
122a0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
122b0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
122c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
122d0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
122e0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
122f0 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
12300 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
12310 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
12320 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
12330 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
12340 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
12350 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
12360 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12370 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
12380 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
12390 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
123a0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
123b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
123c0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
123d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
123e0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
123f0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
12400 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
12410 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
12420 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
12430 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
12440 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
12450 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
12460 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
12470 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
12480 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
12490 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
124a0 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
124b0 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
124c0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
124d0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
124e0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
124f0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12500 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12510 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12520 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12530 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
12540 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
12550 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
12560 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
12570 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
12580 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
12590 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
125a0 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
125b0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
125c0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
125d0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
125e0 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
125f0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12600 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12610 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12620 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
12630 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12640 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
12650 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
12660 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12670 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
12680 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12690 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
126a0 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
126b0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
126c0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
126d0 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
126e0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
126f0 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
12700 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12710 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
12720 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
12730 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
12740 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
12750 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
12760 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
12770 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12780 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
12790 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
127a0 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
127b0 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
127c0 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
127d0 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
127e0 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
127f0 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
12800 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
12810 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
12820 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
12830 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
12840 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
12850 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12860 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12870 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12880 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12890 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
128a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
128b0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
128c0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
128d0 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
128e0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
128f0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
12900 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12910 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
12920 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
12930 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
12940 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12950 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
12960 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
12970 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12990 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
129a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
129b0 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
129c0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
129d0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
129e0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
129f0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
12a00 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
12a10 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
12a20 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
12a30 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
12a40 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
12a50 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
12a60 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
12a70 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
12a80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12a90 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12aa0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
12ab0 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
12ac0 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
12ad0 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
12ae0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12af0 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
12b00 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
12b10 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
12b20 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
12b30 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
12b40 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
12b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
12b60 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12b70 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
12b80 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
12b90 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
12ba0 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
12bb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12bc0 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
12bd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12be0 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
12bf0 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
12c00 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
12c10 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12c20 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12c30 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12c40 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12c50 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12c60 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12c70 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
12c80 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
12c90 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
12ca0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12cb0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
12cc0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12cd0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12ce0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
12cf0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
12d00 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
12d10 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
12d20 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12d30 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12d40 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
12d50 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12d60 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
12d70 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
12d80 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12d90 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12da0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12db0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
12dc0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
12dd0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
12de0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12df0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
12e00 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
12e10 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
12e20 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
12e30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12e40 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
12e50 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
12e60 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
12e70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12e80 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
12e90 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
12ea0 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
12eb0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
12ec0 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
12ed0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12ee0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12ef0 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
12f00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
12f10 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
12f20 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
12f30 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12f40 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
12f50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12f60 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
12f70 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
12f80 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12f90 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
12fa0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12fb0 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
12fc0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12fd0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12fe0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12ff0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
13000 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
13010 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
13020 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
13030 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
13040 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
13050 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13060 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
13070 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
13080 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
13090 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
130a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
130b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
130c0 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
130d0 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
130e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
130f0 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
13100 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
13110 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
13120 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13130 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
13140 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
13150 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13160 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
13170 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13180 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74  IG_MEMSTATUS opt
13190 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
131a0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
131b0 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70  e int,.** interp
131c0 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
131d0 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
131e0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
131f0 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a  e collection of.
13200 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
13210 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e  tion statistics.
13220 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
13230 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
13240 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  tics are.** disa
13250 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
13260 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
13270 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
13280 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
13290 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
132a0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
132b0 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
132c0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
132d0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
132e0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
132f0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
13300 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
13310 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
13320 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  us64()].**   </u
13330 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
13340 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
13350 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
13360 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
13370 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
13380 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
13390 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
133a0 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
133b0 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
133c0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
133d0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
133e0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
133f0 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
13400 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13410 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
13420 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13430 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
13440 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
13450 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70  ONFIG_SCRATCH op
13460 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
13470 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
13480 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51  uffer.** that SQ
13490 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
134a0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
134b0 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68    ^(There are th
134c0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ree arguments.**
134d0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
134e0 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f  G_SCRATCH:  A po
134f0 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a  inter an 8-byte.
13500 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  ** aligned memor
13510 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68  y buffer from wh
13520 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20  ich the scratch 
13530 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
13540 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
13550 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
13560 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
13570 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
13580 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
13590 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
135a0 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a  ocations (N).)^.
135b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
135c0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
135d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
135e0 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
135f0 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
13600 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
13610 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
13620 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65  ite will not use
13630 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73   more than one s
13640 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
13650 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53  er thread..** ^S
13660 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
13670 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74   request a scrat
13680 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
13690 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
136a0 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
136b0 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a  ase page size..*
136c0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  * ^If SQLite nee
136d0 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
136e0 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
136f0 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
13700 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
13710 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
13720 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
13730 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
13740 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
13750 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
13760 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
13770 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  .<p>.** ^When th
13780 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72  e application pr
13790 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e  ovides any amoun
137a0 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d  t of scratch mem
137b0 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ory using.** SQL
137c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
137d0 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64  CH, SQLite avoid
137e0 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61  s unnecessary la
137f0 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rge.** [sqlite3_
13800 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f  malloc|heap allo
13810 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69  cations]..** Thi
13820 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73  s can help [Robs
13830 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74  on proof|prevent
13840 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13850 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65  on failures] due
13860 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67   to heap.** frag
13870 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77  mentation in low
13880 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64  -memory embedded
13890 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64   systems..** </d
138a0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
138b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
138c0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
138d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
138e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
138f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13900 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f  _PAGECACHE optio
13910 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65  n specifies a me
13920 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61  mory pool.** tha
13930 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
13940 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
13950 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
13960 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
13970 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
13980 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
13990 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
139a0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20  ion option is a 
139b0 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c  no-op if an appl
139c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
139d0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
139e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
139f0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
13a00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13a10 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65  CACHE2]..** ^The
13a20 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
13a30 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
13a40 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13a50 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
13a60 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
13a70 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c  d memory (pMem),
13a80 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
13a90 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  h page cache lin
13aa0 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  e (sz),.** and t
13ab0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63  he number of cac
13ac0 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a  he lines (N)..**
13ad0 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
13ae0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
13af0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
13b00 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
13b10 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
13b20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
13b30 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
13b40 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
13b50 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
13b60 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
13b70 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
13b80 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
13b90 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
13ba0 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
13bb0 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49  ined using [SQLI
13bc0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13bd0 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20  _HDRSZ]..** ^It 
13be0 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
13bf0 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
13c00 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f  ed memory,.** fo
13c10 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74  r the sz paramet
13c20 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20  er to be larger 
13c30 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20  than necessary. 
13c40 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67   The pMem.** arg
13c50 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69  ument must be ei
13c60 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
13c70 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ter or a pointer
13c80 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
13c90 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f   aligned block o
13ca0 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  f memory of at l
13cb0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c  east sz*N bytes,
13cc0 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75   otherwise.** su
13cd0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
13ce0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
13cf0 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73  ** ^When pMem is
13d00 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
13d10 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f  e will strive to
13d20 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
13d30 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73  provided.** to s
13d40 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68  atisfy page cach
13d50 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67  e needs, falling
13d60 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65   back to [sqlite
13d70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a  3_malloc()] if.*
13d80 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c  * a page cache l
13d90 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68  ine is larger th
13da0 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69  an sz bytes or i
13db0 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65  f all of the pMe
13dc0 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65  m buffer.** is e
13dd0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66  xhausted..** ^If
13de0 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e   pMem is NULL an
13df0 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  d N is non-zero,
13e00 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62   then each datab
13e10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
13e20 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61  * does an initia
13e30 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f  l bulk allocatio
13e40 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  n for page cache
13e50 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20   memory.** from 
13e60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13e70 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f  )] sufficient fo
13e80 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20  r N cache lines 
13e90 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
13ea0 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a   or.** of -1024*
13eb0 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20  N bytes if N is 
13ec0 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20  negative, . ^If 
13ed0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
13ee0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
13ef0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
13f00 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
13f10 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c  d by the initial
13f20 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  .** allocation, 
13f30 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73  then SQLite goes
13f40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13f50 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c  loc()] separatel
13f60 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64  y for each.** ad
13f70 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c  ditional cache l
13f80 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ine. </dd>.**.**
13f90 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13fa0 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
13fb0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
13fc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13fd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
13fe0 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
13ff0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
14000 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
14010 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
14020 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
14030 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
14040 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14050 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
14060 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
14070 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
14080 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a  IG_SCRATCH] and.
14090 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
140a0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
140b0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
140c0 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
140d0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
140e0 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
140f0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
14100 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
14110 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
14120 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
14130 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
14140 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
14150 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
14160 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
14170 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
14180 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
14190 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
141a0 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
141b0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
141c0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
141d0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
141e0 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
141f0 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
14200 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
14210 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
14220 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
14230 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14240 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
14250 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
14260 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
14270 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
14280 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14290 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
142a0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
142b0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
142c0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
142d0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
142e0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
142f0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
14300 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
14310 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
14320 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
14330 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
14340 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
14350 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
14360 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
14370 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
14380 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
14390 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
143a0 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
143b0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
143c0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
143d0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
143e0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
143f0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
14400 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
14410 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
14420 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
14430 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
14440 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
14450 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
14460 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
14470 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
14480 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
14490 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
144a0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
144b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
144c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
144d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
144e0 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
144f0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14500 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
14510 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
14520 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14530 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
14540 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14550 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
14560 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
14570 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
14580 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
14590 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
145a0 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
145b0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
145c0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
145d0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
145e0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
145f0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
14600 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
14610 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14620 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
14630 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
14640 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
14650 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
14660 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
14670 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
14680 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
14690 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
146a0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
146b0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
146c0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
146d0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
146e0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
146f0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
14700 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
14710 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
14720 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
14730 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
14740 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14750 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
14760 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
14770 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14780 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14790 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
147a0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
147b0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
147c0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
147d0 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
147e0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
147f0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14800 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
14810 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
14820 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14830 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
14840 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
14850 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
14860 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
14870 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
14880 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
14890 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
148a0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
148b0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
148c0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
148d0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
148e0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
148f0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
14900 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
14910 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
14920 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
14930 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
14940 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
14950 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
14960 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14970 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
14980 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
14990 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
149a0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
149b0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
149c0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
149d0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
149e0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
149f0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
14a00 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
14a10 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14a20 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
14a30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14a40 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
14a50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
14a60 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
14a70 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
14a80 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14a90 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14aa0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
14ab0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
14ac0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14ad0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14ae0 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
14af0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
14b00 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
14b10 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
14b20 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
14b30 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
14b40 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
14b50 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
14b60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14b70 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
14b80 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
14b90 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
14ba0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
14bb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
14bc0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
14bd0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
14be0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
14bf0 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
14c00 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
14c10 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
14c20 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
14c30 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
14c40 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
14c50 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
14c60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
14c70 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
14c80 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
14c90 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
14ca0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14cb0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
14cc0 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
14cd0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14ce0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
14cf0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14d00 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
14d10 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14d20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14d30 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
14d40 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14d50 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
14d60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14d70 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
14d80 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14d90 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
14da0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
14db0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
14dc0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
14dd0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14de0 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
14df0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
14e00 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
14e10 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14e20 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
14e30 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14e40 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
14e50 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14e60 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
14e70 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14e80 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14e90 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14ea0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14eb0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
14ec0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14ed0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
14ee0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14ef0 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
14f00 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
14f10 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
14f20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
14f30 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
14f40 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
14f50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14f60 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
14f70 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
14f80 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
14f90 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
14fa0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
14fb0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
14fc0 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
14fd0 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
14fe0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14ff0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
15000 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
15010 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
15020 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
15030 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
15040 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
15050 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
15060 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
15070 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
15080 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
15090 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
150a0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
150b0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
150c0 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
150d0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
150e0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
150f0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
15100 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
15110 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
15120 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
15130 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
15140 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
15150 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
15160 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15170 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
15180 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
15190 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
151a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
151b0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
151c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
151d0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
151e0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
151f0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
15200 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
15210 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
15220 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
15230 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
15240 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
15250 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
15260 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
15270 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
15280 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
15290 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
152a0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
152b0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
152c0 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
152d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
152e0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
152f0 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
15300 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
15310 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
15320 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
15330 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
15340 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
15350 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
15360 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
15370 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
15380 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
15390 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
153a0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
153b0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
153c0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
153d0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
153e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
153f0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
15400 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
15410 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
15420 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15430 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
15440 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15450 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
15460 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15470 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
15480 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15490 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
154a0 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
154b0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
154c0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
154d0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
154e0 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
154f0 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
15500 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
15510 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
15520 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
15530 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
15540 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
15550 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
15560 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
15570 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
15580 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
15590 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
155a0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
155b0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
155c0 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
155d0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
155e0 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
155f0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
15600 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
15610 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
15620 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
15630 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
15640 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
15650 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
15660 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
15670 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
15680 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
15690 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
156a0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
156b0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
156c0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
156d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
156e0 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
156f0 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
15700 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
15710 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
15720 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
15730 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
15740 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
15750 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
15760 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
15770 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
15780 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15790 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
157a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
157b0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
157c0 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
157d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
157e0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
157f0 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
15800 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
15810 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
15820 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
15830 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
15840 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
15850 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
15860 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
15870 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
15880 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
15890 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
158a0 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
158b0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
158c0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
158d0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
158e0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
158f0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
15900 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15910 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
15920 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
15930 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
15940 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
15950 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
15960 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
15970 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
15980 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
15990 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
159a0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
159b0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
159c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
159d0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
159e0 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
159f0 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
15a00 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
15a10 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
15a20 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
15a30 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
15a40 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
15a50 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
15a60 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
15a70 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
15a80 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
15a90 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
15aa0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15ab0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
15ac0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15ad0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
15ae0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15af0 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
15b00 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15b10 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
15b20 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
15b30 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
15b40 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
15b50 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
15b60 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
15b70 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
15b80 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
15b90 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
15ba0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
15bb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15bc0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
15bd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
15be0 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
15bf0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
15c00 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
15c10 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15c20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
15c30 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
15c40 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
15c50 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
15c60 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15c70 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
15c80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
15c90 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
15ca0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
15cb0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
15cc0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
15cd0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
15ce0 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
15cf0 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
15d00 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
15d10 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
15d20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
15d30 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
15d40 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
15d50 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
15d60 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
15d70 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
15d80 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15d90 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
15da0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15db0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
15dc0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
15dd0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
15de0 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
15df0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
15e00 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
15e10 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
15e20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
15e30 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
15e40 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
15e50 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
15e60 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
15e70 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
15e80 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
15e90 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
15ea0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
15eb0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
15ec0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
15ed0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
15ee0 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
15ef0 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
15f00 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
15f10 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
15f20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
15f30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
15f40 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
15f50 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
15f60 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
15f70 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
15f80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
15f90 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
15fa0 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
15fb0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
15fc0 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
15fd0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
15fe0 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
15ff0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16000 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
16010 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16020 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
16030 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
16040 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
16050 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
16060 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
16070 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
16080 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
16090 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
160a0 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
160b0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
160c0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
160d0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
160e0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
160f0 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
16100 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
16110 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
16120 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
16130 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16140 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
16150 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
16160 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
16170 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
16180 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
16190 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
161a0 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
161b0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
161c0 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
161d0 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
161e0 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
161f0 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
16200 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
16210 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
16220 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
16230 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
16240 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
16250 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
16260 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16270 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
16280 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
16290 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
162a0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
162b0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
162c0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
162d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
162e0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
162f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
16300 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
16310 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16320 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
16330 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
16340 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16350 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
16360 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
16370 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
16380 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
16390 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
163a0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
163b0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
163c0 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
163d0 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
163e0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
163f0 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
16400 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
16410 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
16420 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
16430 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
16440 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
16450 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
16460 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
16470 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
16480 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16490 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
164a0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
164b0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
164c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
164d0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
164e0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
164f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
16500 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
16510 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
16520 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
16530 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
16540 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
16550 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
16560 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
16570 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
16580 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
16590 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
165a0 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
165b0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
165c0 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
165d0 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
165e0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
165f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16600 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
16610 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16620 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
16630 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
16640 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
16650 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16660 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
16670 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
16680 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
16690 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
166a0 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
166b0 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
166c0 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
166d0 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
166e0 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
166f0 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
16700 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
16710 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
16720 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16730 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
16740 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
16750 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
16760 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
16770 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
16780 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
16790 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
167a0 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
167b0 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
167c0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
167d0 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
167e0 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
167f0 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
16800 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
16810 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
16820 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
16830 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
16840 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  lue..**.** [[SQL
16850 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
16860 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c  RNL_SPILL]].** <
16870 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16880 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a  _STMTJRNL_SPILL.
16890 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
168a0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
168b0 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20  NL_SPILL option 
168c0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
168d0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
168e0 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73  * becomes the [s
168f0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
16900 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20  ] spill-to-disk 
16910 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20  threshold.  .** 
16920 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [Statement journ
16930 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e  als] are held in
16940 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68   memory until th
16950 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74  eir size (in byt
16960 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74  es).** exceeds t
16970 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61  his threshold, a
16980 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68  t which point th
16990 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74  ey are written t
169a0 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66  o disk..** Or if
169b0 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69   the threshold i
169c0 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20  s -1, statement 
169d0 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77  journals are alw
169e0 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c  ays held.** excl
169f0 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72  usively in memor
16a00 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79  y..** Since many
16a10 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
16a20 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65  als never become
16a30 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20   large, setting 
16a40 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72  the spill.** thr
16a50 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75  eshold to a valu
16a60 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20  e such as 64KiB 
16a70 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75  can greatly redu
16a80 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ce the amount of
16a90 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64  .** I/O required
16aa0 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74   to support stat
16ab0 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a  ement rollback..
16ac0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
16ad0 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65  alue for this se
16ae0 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c  tting is control
16af0 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  led by the.** [S
16b00 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53  QLITE_STMTJRNL_S
16b10 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  PILL] compile-ti
16b20 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f  me option..** </
16b30 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
16b40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
16b50 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
16b60 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
16b70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
16b80 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
16b90 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
16ba0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16bb0 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
16bc0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16bd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16be0 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
16bf0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
16c00 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
16c10 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16c20 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
16c30 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
16c40 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
16c50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16c60 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
16c70 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
16c80 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
16c90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16ca0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
16cb0 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
16cc0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
16cd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16ce0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
16cf0 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
16d00 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
16d10 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
16d20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16d30 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
16d40 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
16d50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16d60 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
16d70 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
16d80 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
16d90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16da0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
16db0 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
16dc0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16dd0 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
16de0 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
16df0 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
16e00 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
16e10 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
16e20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16e30 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
16e40 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
16e50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16e60 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
16e70 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   14  /* no-op */
16e80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16e90 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16ea0 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70      15  /* no-op
16eb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16ec0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
16ed0 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
16ee0 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
16ef0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16f00 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
16f10 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   17  /* int */.#
16f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f30 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20  NFIG_PCACHE2    
16f40 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33    18  /* sqlite3
16f50 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
16f60 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16f70 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16f80 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73  ACHE2   19  /* s
16f90 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
16fa0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
16fb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16fc0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
16fd0 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20  SCAN 20  /* int 
16fe0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16ff0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20  E_CONFIG_SQLLOG 
17000 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71        21  /* xSq
17010 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  llog, void* */.#
17020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17030 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  NFIG_MMAP_SIZE  
17040 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33    22  /* sqlite3
17050 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f  _int64, sqlite3_
17060 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65  int64 */.#define
17070 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
17080 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20  IN32_HEAPSIZE   
17090 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42     23  /* int nB
170a0 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  yte */.#define S
170b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
170c0 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20  CHE_HDRSZ       
170d0 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a   24  /* int *psz
170e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
170f0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
17100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
17110 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e    /* unsigned in
17120 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69  t szPma */.#defi
17130 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17140 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20  _STMTJRNL_SPILL 
17150 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e 74 20       26  /* int 
17160 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nByte */../*.** 
17170 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
17180 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
17190 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
171a0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
171b0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
171c0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
171d0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
171e0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
171f0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
17200 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
17210 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
17220 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17230 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
17240 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
17250 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
17260 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
17270 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
17280 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
17290 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
172a0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
172b0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
172c0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
172d0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
172e0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
172f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
17300 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
17310 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
17320 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
17330 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
17340 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
17350 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
17360 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
17370 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
17380 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
17390 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
173a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
173b0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
173c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
173d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
173e0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
173f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17400 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
17410 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
17420 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
17430 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
17440 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
17450 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
17460 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
17470 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
17480 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
17490 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
174a0 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
174b0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
174c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
174d0 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
174e0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
174f0 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
17500 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
17510 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
17520 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
17530 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
17540 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
17550 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
17560 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
17570 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
17580 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
17590 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
175a0 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
175b0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
175c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
175d0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
175e0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
175f0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
17600 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
17610 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
17620 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
17630 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
17640 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
17650 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
17660 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
17670 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
17680 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
17690 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
176a0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
176b0 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
176c0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
176d0 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
176e0 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
176f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
17700 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
17710 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
17720 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
17730 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
17740 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
17750 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
17760 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
17770 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
17780 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
17790 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
177a0 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
177b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
177c0 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
177d0 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
177e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
177f0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
17800 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
17810 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
17820 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
17830 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
17840 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
17850 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
17860 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
17870 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
17880 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
17890 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
178a0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
178b0 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
178c0 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
178d0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
178e0 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
178f0 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
17900 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
17910 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
17920 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
17930 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17940 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17950 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
17960 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
17970 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
17980 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
17990 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
179a0 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
179b0 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
179c0 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
179d0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
179e0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
179f0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
17a00 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
17a10 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
17a20 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
17a30 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
17a40 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
17a50 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
17a60 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
17a70 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
17a80 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
17a90 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17aa0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
17ab0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
17ac0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
17ad0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
17ae0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
17af0 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
17b00 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
17b10 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
17b20 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
17b30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
17b40 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
17b50 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
17b60 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
17b70 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
17b80 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
17b90 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
17ba0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17bb0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
17bc0 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
17bd0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17be0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17bf0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
17c00 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
17c10 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
17c20 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
17c30 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
17c40 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
17c50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
17c60 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
17c70 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
17c80 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
17c90 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
17ca0 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
17cb0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
17cc0 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
17cd0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
17ce0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
17cf0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
17d00 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
17d10 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
17d20 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
17d30 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
17d40 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
17d50 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
17d60 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
17d70 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
17d80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
17d90 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
17da0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
17db0 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
17dc0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
17dd0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
17de0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
17df0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
17e00 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e  NABLE_FTS3_TOKEN
17e10 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZER</dt>.** <dd
17e20 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
17e30 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
17e40 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
17e50 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  two-argument.** 
17e60 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b  version of the [
17e70 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
17e80 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68  ] function which
17e90 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   is part of the.
17ea0 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74  ** [FTS3] full-t
17eb0 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69 6e  ext search engin
17ec0 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20  e extension..** 
17ed0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17ee0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17ef0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17f00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17f10 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17f20 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17f30 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
17f40 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74  er() or.** posit
17f50 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66 74  ive to enable ft
17f60 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f  s3_tokenizer() o
17f70 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
17f80 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a  ave the setting.
17f90 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ** unchanged..**
17fa0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17fb0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
17fc0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
17fd0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
17fe0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
17ff0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
18000 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69  ther fts3_tokeni
18010 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
18020 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
18030 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
18040 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
18050 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
18060 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
18070 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
18080 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67   the new setting
18090 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
180a0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
180b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
180c0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f  CONFIG_ENABLE_LO
180d0 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74  AD_EXTENSION</dt
180e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
180f0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
18100 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
18110 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ble the [sqlite3
18120 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18130 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
18140 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66  independently of
18150 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e   the [load_exten
18160 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63  sion()] SQL func
18170 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  tion..** The [sq
18180 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
18190 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41  d_extension()] A
181a0 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  PI enables or di
181b0 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a  sables both the.
181c0 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65  ** C-API [sqlite
181d0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
181e0 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ()] and the SQL 
181f0 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65  function [load_e
18200 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20  xtension()]..** 
18210 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
18220 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
18230 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65  rguments..** Whe
18240 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
18250 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74  ment to this int
18260 65 72 66 61 63 65 20 69 73 20 31 2c 20 74 68 65  erface is 1, the
18270 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49  n only the C-API
18280 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61   is.** enabled a
18290 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
182a0 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61  ion remains disa
182b0 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66 69  bled.  If the fi
182c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  rst argument to.
182d0 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ** this interfac
182e0 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74  e is 0, then bot
182f0 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20  h the C-API and 
18300 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
18310 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a   are disabled..*
18320 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61  * If the first a
18330 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74  rgument is -1, t
18340 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61  hen no changes a
18350 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65  re made to state
18360 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a   of either the.*
18370 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53  * C-API or the S
18380 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  QL function..** 
18390 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
183a0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
183b0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
183c0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
183d0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
183e0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
183f0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  her [sqlite3_loa
18400 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69  d_extension()] i
18410 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64  nterface.** is d
18420 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
18430 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ed following thi
18440 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
18450 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
18460 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70  y.** be a NULL p
18470 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68  ointer, in which
18480 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65   case the new se
18490 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
184a0 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c  orted back..** <
184b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
184c0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d  QLITE_DBCONFIG_M
184d0 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a  AINDBNAME</dt>.*
184e0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
184f0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
18500 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65 20 6f  hange the name o
18510 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64 61 74  f the "main" dat
18520 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e  abase.** schema.
18530 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72 67 75    ^The sole argu
18540 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
18550 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20  r to a constant 
18560 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77  UTF8 string.** w
18570 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65  hich will become
18580 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d 61 20   the new schema 
18590 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  name in place of
185a0 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74   "main".  ^SQLit
185b0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61  e.** does not ma
185c0 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ke a copy of the
185d0 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65 6d 61   new main schema
185e0 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f   name string, so
185f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
18600 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
18610 74 68 61 74 20 74 68 65 20 61 72 67 75 6d 65 6e  that the argumen
18620 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  t passed into th
18630 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70 74 69  is DBCONFIG opti
18640 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65 64 0a  on is unchanged.
18650 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ** until after t
18660 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18670 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
18680 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
18690 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
186a0 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f  G_NO_CKPT_ON_CLO
186b0 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  SE</dt>.** <dd> 
186c0 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 61 20  Usually, when a 
186d0 64 61 74 61 62 61 73 65 20 69 6e 20 77 61 6c 20  database in wal 
186e0 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64 20 6f  mode is closed o
186f0 72 20 64 65 74 61 63 68 65 64 20 66 72 6f 6d 20  r detached from 
18700 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68  a .** database h
18710 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20 63 68  andle, SQLite ch
18720 65 63 6b 73 20 69 66 20 74 68 69 73 20 77 69 6c  ecks if this wil
18730 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 72  l mean that ther
18740 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a  e are now no .**
18750 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 74 20   connections at 
18760 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74 61 62  all to the datab
18770 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74 20 70  ase. If so, it p
18780 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63 6b 70  erforms a checkp
18790 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 74 69  oint .** operati
187a0 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73 69 6e  on before closin
187b0 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  g the connection
187c0 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d 61  . This option ma
187d0 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20  y be used to.** 
187e0 6f 76 65 72 72 69 64 65 20 74 68 69 73 20 62 65  override this be
187f0 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66 69 72  haviour. The fir
18800 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  st parameter pas
18810 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65 72  sed to this oper
18820 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20 69  ation.** is an i
18830 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a 65 72  nteger - non-zer
18840 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 63 68 65  o to disable che
18850 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73  ckpoints-on-clos
18860 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68 65 0a  e, or zero (the.
18870 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f 20 65  ** default) to e
18880 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 68 65 20  nable them. The 
18890 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
188a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
188b0 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 69   an integer.** i
188c0 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 72 69  nto which is wri
188d0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
188e0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
188f0 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63  checkpoints-on-c
18900 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62 65 65  lose.** have bee
18910 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30 20 69  n disabled - 0 i
18920 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 64  f they are not d
18930 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20 74 68  isabled, 1 if th
18940 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e  ey are..** </dd>
18950 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
18960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18970 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41  BCONFIG_MAINDBNA
18980 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 31 30  ME            10
18990 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72  00 /* const char
189a0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
189b0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
189c0 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20  KASIDE          
189d0 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a     1001 /* void*
189e0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
189f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18a00 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
18a10 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f            1002 /
18a20 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
18a30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18a40 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
18a50 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33  GGER        1003
18a60 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18a70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18a80 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
18a90 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30  TS3_TOKENIZER 10
18aa0 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  04 /* int int* *
18ab0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18ac0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18ad0 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20  _LOAD_EXTENSION 
18ae0 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1005 /* int int*
18af0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18b00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
18b10 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20  KPT_ON_CLOSE    
18b20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e    1006 /* int in
18b30 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
18b40 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
18b50 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
18b60 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
18b70 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
18b80 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
18b90 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
18ba0 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
18bb0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
18bc0 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
18bd0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
18be0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
18bf0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
18c00 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
18c10 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
18c20 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
18c30 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
18c40 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
18c50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
18c60 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
18c70 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
18c80 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
18c90 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
18ca0 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
18cb0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
18cc0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
18cd0 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74  ry in most SQLit
18ce0 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74  e tables (except
18cf0 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f   for [WITHOUT RO
18d00 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20  WID] tables).** 
18d10 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
18d20 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
18d30 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
18d40 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
18d50 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
18d60 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
18d70 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
18d80 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
18d90 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
18da0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
18db0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
18dc0 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
18dd0 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
18de0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
18df0 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
18e00 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
18e10 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
18e20 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
18e30 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
18e40 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
18e50 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
18e60 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
18e70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61   ^The sqlite3_la
18e80 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
18e90 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  D) interface ret
18ea0 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
18eb0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74   of the .** most
18ec0 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
18ed0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
18ee0 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
18ef0 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
18f00 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
18f10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
18f20 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20  * ^Inserts into 
18f30 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
18f40 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72  tables are not r
18f50 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  ecorded..** ^If 
18f60 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
18f70 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77  NSERT]s into row
18f80 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76  id tables.** hav
18f90 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
18fa0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
18fb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a  connection D, .*
18fc0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c  * then sqlite3_l
18fd0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
18fe0 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (D) returns zero
18ff0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
19000 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
19010 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
19020 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
19030 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
19040 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
19050 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
19060 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
19070 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
19080 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
19090 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
190a0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
190b0 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
190c0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
190d0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
190e0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
190f0 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
19100 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
19110 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
19120 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
19130 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
19140 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
19150 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
19160 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
19170 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
19180 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
19190 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
191a0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
191b0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
191c0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
191d0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
191e0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
191f0 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
19200 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
19210 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
19220 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
19230 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
19240 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
19250 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
19260 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
19270 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
19280 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
19290 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
192a0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
192b0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
192c0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
192d0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
192e0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
192f0 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
19300 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
19310 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
19320 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
19330 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
19340 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
19350 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
19360 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
19370 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
19380 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
19390 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
193a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
193b0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
193c0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
193d0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
193e0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
193f0 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
19400 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
19410 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
19420 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
19430 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
19440 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
19450 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
19460 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
19470 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19480 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
19490 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
194a0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
194b0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
194c0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
194d0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
194e0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
194f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
19500 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19510 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
19520 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
19530 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
19540 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
19550 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
19560 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19570 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
19580 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
19590 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
195a0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
195b0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
195c0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
195d0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
195e0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
195f0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
19600 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19610 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
19620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
19630 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
19640 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
19650 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
19660 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
19670 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
19680 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
19690 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e  ows modified, in
196a0 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  serted or.** del
196b0 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
196c0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
196d0 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
196e0 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  TE or DELETE.** 
196f0 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
19700 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19710 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62  tion specified b
19720 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  y the only param
19730 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74  eter..** ^Execut
19740 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
19750 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
19760 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64  ent does not mod
19770 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  ify the value.**
19780 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
19790 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
197a0 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  * ^Only changes 
197b0 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79  made directly by
197c0 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
197d0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
197e0 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63  atement are.** c
197f0 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69  onsidered - auxi
19800 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
19810 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20  used by [CREATE 
19820 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
19830 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67  rs], .** [foreig
19840 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f  n key actions] o
19850 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  r [REPLACE] cons
19860 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
19870 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  n are not counte
19880 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65  d..** .** Change
19890 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
198a0 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
198b0 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44   by .** [INSTEAD
198c0 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e   OF trigger | IN
198d0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
198e0 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
198f0 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a  ed. ^The value .
19900 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
19910 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19920 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
19930 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  er an INSERT, UP
19940 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45  DATE or .** DELE
19950 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e  TE statement run
19960 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c   on a view is al
19970 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20  ways zero. Only 
19980 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20  changes made to 
19990 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20  real .** tables 
199a0 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
199b0 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f  ** Things are mo
199c0 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69  re complicated i
199d0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  f the sqlite3_ch
199e0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
199f0 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   is.** executed 
19a00 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20  while a trigger 
19a10 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69  program is runni
19a20 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70  ng. This may hap
19a30 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72  pen if the.** pr
19a40 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b  ogram uses the [
19a50 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
19a60 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73  nction], or if s
19a70 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61  ome other callba
19a80 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ck.** function i
19a90 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63  nvokes sqlite3_c
19aa0 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c  hanges() directl
19ab0 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a  y. Essentially:.
19ac0 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  ** .** <ul>.**  
19ad0 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65   <li> ^(Before e
19ae0 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65  ntering a trigge
19af0 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61  r program the va
19b00 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  lue returned by.
19b10 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65  **        sqlite
19b20 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
19b30 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41  tion is saved. A
19b40 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72  fter the trigger
19b50 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20   program .**    
19b60 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64      has finished
19b70 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76  , the original v
19b80 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64  alue is restored
19b90 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69  .)^.** .**   <li
19ba0 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69  > ^(Within a tri
19bb0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63  gger program eac
19bc0 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  h INSERT, UPDATE
19bd0 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20   and DELETE .** 
19be0 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
19bf0 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20   sets the value 
19c00 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
19c10 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
19c20 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f  *        upon co
19c30 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d  mpletion as norm
19c40 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74  al. Of course, t
19c50 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e  his value will n
19c60 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20  ot include .**  
19c70 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65        any change
19c80 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73  s performed by s
19c90 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20  ub-triggers, as 
19ca0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
19cb0 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
19cc0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73   value will be s
19cd0 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65  aved and restore
19ce0 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62  d after each sub
19cf0 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e  -trigger has run
19d00 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  .)^.** </ul>.** 
19d10 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20  .** ^This means 
19d20 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e  that if the chan
19d30 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
19d40 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20  on (or similar) 
19d50 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  is used.** by th
19d60 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20  e first INSERT, 
19d70 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
19d80 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
19d90 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20  n a trigger, it 
19da0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
19db0 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65  value as set whe
19dc0 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74  n the calling st
19dd0 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78  atement began ex
19de0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20  ecuting..** ^If 
19df0 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68  it is used by th
19e00 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73  e second or subs
19e10 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74  equent such stat
19e20 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
19e30 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72  rigger .** progr
19e40 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  am, the value re
19e50 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20  turned reflects 
19e60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
19e70 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74  ws modified by t
19e80 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  he .** previous 
19e90 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
19ea0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
19eb0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
19ec0 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a  me trigger..**.*
19ed0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
19ee0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
19ef0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
19f00 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
19f10 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
19f20 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
19f30 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
19f40 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
19f50 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
19f60 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
19f70 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
19f80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
19f90 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
19fa0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
19fb0 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
19fc0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
19fd0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
19fe0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
19ff0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
1a000 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
1a010 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1a020 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
1a030 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1a040 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
1a050 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1a060 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1a070 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
1a080 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1a090 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
1a0a0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1a0b0 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
1a0c0 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
1a0d0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
1a0e0 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
1a0f0 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
1a100 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
1a110 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
1a120 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
1a130 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
1a140 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
1a150 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
1a160 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1a170 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1a180 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
1a190 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a1a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
1a1b0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
1a1c0 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
1a1d0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
1a1e0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1a1f0 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
1a200 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
1a210 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
1a220 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
1a230 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
1a240 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
1a250 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
1a260 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
1a270 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
1a280 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
1a290 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
1a2a0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
1a2b0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
1a2c0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a2d0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
1a2e0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
1a2f0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
1a300 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
1a310 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1a320 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1a330 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1a340 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
1a350 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1a360 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1a370 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1a380 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1a390 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1a3a0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
1a3b0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
1a3c0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
1a3d0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
1a3e0 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
1a3f0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1a400 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1a410 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
1a420 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
1a430 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ery.** METHOD: s
1a440 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1a450 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
1a460 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
1a470 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1a480 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
1a490 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
1a4a0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
1a4b0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
1a4c0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
1a4d0 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
1a4e0 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
1a4f0 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
1a500 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
1a510 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
1a520 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
1a530 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
1a540 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
1a550 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
1a560 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
1a570 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1a580 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
1a590 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
1a5a0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
1a5b0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
1a5c0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
1a5d0 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
1a5e0 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
1a5f0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1a600 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1a610 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
1a620 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
1a630 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
1a640 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
1a650 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
1a660 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
1a670 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
1a680 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1a690 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
1a6a0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
1a6b0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
1a6c0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
1a6d0 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
1a6e0 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
1a6f0 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
1a700 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
1a710 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
1a720 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
1a730 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
1a740 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
1a750 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
1a760 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
1a770 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
1a780 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
1a790 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
1a7a0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
1a7b0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
1a7c0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
1a7d0 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
1a7e0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
1a7f0 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
1a800 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
1a810 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
1a820 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
1a830 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
1a840 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a850 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
1a860 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
1a870 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1a880 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
1a890 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
1a8a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1a8b0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
1a8c0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
1a8d0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1a8e0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1a8f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a900 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
1a910 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
1a920 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
1a930 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
1a940 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
1a950 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
1a960 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
1a970 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1a980 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1a990 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
1a9a0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1a9b0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1a9c0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
1a9d0 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
1a9e0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
1a9f0 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
1aa00 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
1aa10 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
1aa20 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1aa30 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
1aa40 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
1aa50 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
1aa60 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1aa70 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
1aa80 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
1aa90 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
1aaa0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1aab0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1aac0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1aad0 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
1aae0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
1aaf0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ab00 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
1ab10 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
1ab20 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
1ab30 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
1ab40 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
1ab50 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
1ab60 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1ab70 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1ab80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ab90 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1aba0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1abb0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1abc0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1abd0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1abe0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1abf0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1ac00 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1ac10 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1ac20 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1ac30 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1ac40 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1ac50 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1ac60 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1ac70 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1ac80 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1ac90 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1aca0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1acb0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1acc0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1acd0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1ace0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1acf0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1ad00 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1ad10 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1ad20 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1ad30 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1ad40 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1ad50 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1ad60 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1ad70 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1ad80 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1ad90 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1ada0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1adb0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1adc0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1add0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1ade0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1adf0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1ae00 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1ae10 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1ae20 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1ae30 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1ae40 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1ae50 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1ae60 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1ae70 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1ae80 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1ae90 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1aea0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1aeb0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1aec0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1aed0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1aee0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1aef0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1af00 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1af10 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1af20 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1af30 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1af40 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1af50 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1af60 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1af70 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1af80 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1af90 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1afa0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1afb0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1afc0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1afd0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1afe0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1aff0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1b000 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1b010 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1b020 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1b030 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1b040 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1b050 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1b060 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1b070 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1b080 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1b090 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1b0a0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1b0b0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1b0c0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1b0d0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1b0e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1b0f0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1b100 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1b110 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1b120 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1b130 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1b140 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1b150 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1b160 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1b170 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1b180 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1b190 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1b1a0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1b1b0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1b1c0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
1b1d0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b1e0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1b1f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1b200 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
1b210 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
1b220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
1b230 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
1b240 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
1b250 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
1b260 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79   KEYWORDS: {busy
1b270 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
1b280 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72  k} {busy handler
1b290 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
1b2a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
1b2b0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1b2c0 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74  dler(D,X,P) rout
1b2d0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
1b2e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ack function X.*
1b2f0 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  * that might be 
1b300 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
1b310 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
1b320 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
1b330 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1b340 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1b350 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
1b360 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1b370 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65  onnection] D whe
1b380 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  n another thread
1b390 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
1b3a0 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63  as the table loc
1b3b0 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ked..** The sqli
1b3c0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1b3d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1b3e0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1b3f0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  t.** [sqlite3_bu
1b400 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e  sy_timeout()] an
1b410 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  d [PRAGMA busy_t
1b420 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  imeout]..**.** ^
1b430 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1b440 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
1b450 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
1b460 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1b470 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
1b480 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
1b490 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
1b4a0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
1b4b0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
1b4c0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1b4d0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1b4e0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
1b4f0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1b500 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1b510 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
1b520 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
1b530 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
1b540 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
1b550 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1b560 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
1b570 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
1b580 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1b590 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
1b5a0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
1b5b0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
1b5c0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
1b5d0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1b5e0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
1b5f0 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ked previously f
1b600 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
1b610 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
1b620 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
1b630 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
1b640 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
1b650 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
1b660 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
1b670 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1b680 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
1b690 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   is returned.** 
1b6a0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1b6b0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  on..** ^If the c
1b6c0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1b6d0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
1b6e0 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
1b6f0 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  * is made to acc
1b700 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1b710 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
1b720 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
1b730 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
1b740 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
1b750 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
1b760 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
1b770 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
1b780 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
1b790 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
1b7a0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
1b7b0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
1b7c0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
1b7d0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
1b7e0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
1b7f0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
1b800 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
1b810 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68  E_BUSY].** to th
1b820 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e  e application in
1b830 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
1b840 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68  g the .** busy h
1b850 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
1b860 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
1b870 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
1b880 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1b890 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
1b8a0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
1b8b0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
1b8c0 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
1b8d0 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
1b8e0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1b8f0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
1b900 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
1b910 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
1b920 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
1b930 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
1b940 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
1b950 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
1b960 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1b970 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
1b980 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1b990 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
1b9a0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
1b9b0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1b9c0 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
1b9d0 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
1b9e0 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
1b9f0 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
1ba00 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
1ba10 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
1ba20 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
1ba30 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1ba40 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
1ba50 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
1ba60 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
1ba70 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
1ba80 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
1ba90 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
1baa0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
1bab0 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
1bac0 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
1bad0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
1bae0 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
1baf0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
1bb00 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1bb10 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1bb20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
1bb30 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
1bb40 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1bb50 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
1bb60 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
1bb70 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
1bb80 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1bb90 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
1bba0 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
1bbb0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1bbc0 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20  imeout()].** or 
1bbd0 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47  evaluating [PRAG
1bbe0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d  MA busy_timeout=
1bbf0 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74  N] will change t
1bc00 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  he.** busy handl
1bc10 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61  er and thus clea
1bc20 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  r any previously
1bc30 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65   set busy handle
1bc40 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
1bc50 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
1bc60 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
1bc70 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
1bc80 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
1bc90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1bca0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1bcb0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49  busy handler.  I
1bcc0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a  n other words,.*
1bcd0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1bce0 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  er is not reentr
1bcf0 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ant.  Any such a
1bd00 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
1bd10 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
1bd20 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
1bd30 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
1bd40 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
1bd50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1bd60 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
1bd70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1bd80 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1bd90 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1bda0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1bdb0 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
1bdc0 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a  e3*,int(*)(void*
1bdd0 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f  ,int),void*);../
1bde0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1bdf0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
1be00 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
1be10 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1be20 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1be30 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1be40 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1be50 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1be60 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1be70 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1be80 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1be90 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1bea0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1beb0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1bec0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1bed0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1bee0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1bef0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1bf00 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1bf10 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1bf20 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1bf30 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1bf40 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1bf50 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1bf60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1bf70 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1bf80 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1bf90 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1bfa0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1bfb0 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1bfc0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1bfd0 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1bfe0 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1bff0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1c000 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1c010 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1c020 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1c030 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1c040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1c050 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1c060 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1c070 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1c080 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1c090 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1c0a0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1c0b0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1c0c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1c0d0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1c0e0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1c0f0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1c100 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1c110 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69  sy_timeout].*/.i
1c120 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1c130 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1c140 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1c150 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1c160 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1c170 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1c180 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ries.** METHOD: 
1c190 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
1c1a0 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1c1b0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1c1c0 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1c1d0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1c1e0 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1c1f0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1c200 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1c210 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1c220 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1c230 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1c240 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1c250 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1c260 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1c270 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1c280 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1c290 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1c2a0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1c2b0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1c2c0 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1c2d0 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1c2e0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1c2f0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1c300 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1c310 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1c320 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1c330 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1c340 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1c350 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1c360 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1c370 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1c380 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1c390 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1c3a0 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1c3b0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1c3c0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1c3d0 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1c3e0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1c3f0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1c400 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1c410 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1c420 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1c430 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1c440 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1c450 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1c460 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1c470 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1c480 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1c490 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1c4a0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1c4b0 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1c4c0 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1c4d0 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1c4e0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1c4f0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1c500 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1c510 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1c520 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1c530 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1c540 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1c550 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1c560 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1c570 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1c580 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1c590 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1c5a0 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1c5b0 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1c5c0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1c5d0 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1c5e0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1c5f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1c600 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1c610 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1c620 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1c630 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1c640 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1c650 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1c660 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1c670 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1c680 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1c690 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1c6a0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c6b0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1c6c0 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1c6d0 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1c6e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1c6f0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1c700 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1c710 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1c720 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1c730 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1c740 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1c750 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c760 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1c770 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1c780 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1c790 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1c7a0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1c7b0 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1c7c0 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1c7d0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1c7e0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1c7f0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1c800 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1c810 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1c820 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1c830 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c840 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c850 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1c860 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c870 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1c880 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1c890 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1c8a0 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1c8b0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c8c0 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1c8d0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1c8e0 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1c8f0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1c900 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1c910 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1c920 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1c930 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1c940 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1c950 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1c960 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1c970 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1c980 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1c990 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1c9a0 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1c9b0 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1c9c0 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1c9d0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1c9e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1c9f0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1ca00 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1ca10 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1ca20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1ca30 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1ca40 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1ca50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1ca60 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1ca70 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1ca80 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1ca90 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1caa0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1cab0 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1cac0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1cad0 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1cae0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1caf0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1cb00 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1cb10 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1cb20 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1cb30 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1cb40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1cb50 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1cb60 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1cb70 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1cb80 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1cb90 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1cba0 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1cbb0 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1cbc0 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1cbd0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1cbe0 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1cbf0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1cc00 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1cc10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1cc20 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1cc30 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1cc40 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1cc50 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1cc60 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1cc70 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1cc80 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1cc90 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1cca0 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1ccb0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1ccc0 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1ccd0 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1cce0 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1ccf0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1cd00 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1cd10 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1cd20 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1cd30 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1cd40 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1cd50 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1cd60 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1cd70 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1cd80 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1cd90 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1cda0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1cdb0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1cdc0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1cdd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
1cde0 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
1cdf0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1ce00 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
1ce10 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
1ce20 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
1ce30 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
1ce40 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
1ce50 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
1ce60 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
1ce70 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
1ce80 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
1ce90 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1cea0 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
1ceb0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
1cec0 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
1ced0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1cee0 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
1cef0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1cf00 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
1cf10 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
1cf20 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
1cf30 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
1cf40 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1cf50 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
1cf60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cf70 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
1cf80 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
1cf90 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1cfa0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
1cfb0 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
1cfc0 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
1cfd0 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
1cfe0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
1cff0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1d000 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1d010 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f  es understand mo
1d020 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e  st of the common
1d030 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20   K&R formatting 
1d040 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73  options,.** plus
1d050 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1d060 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f   non-standard fo
1d070 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20  rmats, detailed 
1d080 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74  below..** Note t
1d090 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20  hat some of the 
1d0a0 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72  more obscure for
1d0b0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1d0c0 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43  from recent.** C
1d0d0 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 72  -library standar
1d0e0 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66  ds are omitted f
1d0f0 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65  rom this impleme
1d100 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ntation..**.** ^
1d110 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
1d120 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
1d130 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
1d140 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
1d150 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
1d160 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
1d170 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
1d180 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
1d190 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1d1a0 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
1d1b0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
1d1c0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
1d1d0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
1d1e0 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
1d1f0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
1d200 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
1d210 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d220 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
1d230 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
1d240 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
1d250 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
1d260 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
1d270 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
1d280 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1d290 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
1d2a0 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
1d2b0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
1d2c0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
1d2d0 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
1d2e0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
1d2f0 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
1d300 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1d310 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
1d320 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
1d330 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1d340 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
1d350 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
1d360 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
1d370 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
1d380 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
1d390 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
1d3a0 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
1d3b0 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
1d3c0 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
1d3d0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
1d3e0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
1d3f0 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
1d400 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
1d410 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1d420 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
1d430 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
1d440 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1d450 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
1d460 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
1d470 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
1d480 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
1d490 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
1d4a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
1d4b0 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
1d4c0 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
1d4d0 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
1d4e0 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
1d4f0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
1d500 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1d510 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1d520 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
1d530 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
1d540 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
1d550 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
1d560 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
1d570 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
1d580 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
1d590 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
1d5a0 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
1d5b0 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
1d5c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
1d5d0 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
1d5e0 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
1d5f0 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
1d600 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
1d610 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
1d620 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
1d630 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
1d640 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
1d650 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
1d660 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
1d670 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
1d680 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
1d690 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1d6a0 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1d6b0 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
1d6c0 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
1d6d0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
1d6e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1d6f0 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
1d700 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
1d710 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
1d720 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
1d730 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
1d740 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
1d750 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
1d760 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
1d770 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
1d780 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
1d790 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
1d7a0 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
1d7b0 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61  q", "%Q", "%w" a
1d7c0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1d7d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1d7e0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1d7f0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1d800 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1d810 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1d820 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1d830 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1d840 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1d850 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1d860 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1d870 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1d880 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1d890 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1d8a0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1d8b0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1d8c0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1d8d0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1d8e0 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1d8f0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1d900 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1d910 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1d920 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1d930 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1d940 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1d950 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1d960 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1d970 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1d980 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1d990 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1d9a0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1d9b0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1d9c0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1d9d0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1d9e0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1d9f0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1da00 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1da10 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1da20 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1da30 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1da40 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1da50 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1da60 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1da70 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1da80 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1da90 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1daa0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1dab0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1dac0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1dad0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1dae0 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1daf0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1db00 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1db10 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1db20 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1db30 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1db40 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1db50 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1db60 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1db70 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1db80 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1db90 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1dba0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1dbb0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1dbc0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1dbd0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1dbe0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1dbf0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1dc00 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1dc10 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1dc20 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1dc30 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1dc40 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1dc50 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1dc60 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1dc70 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1dc80 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1dc90 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1dca0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1dcb0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1dcc0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1dcd0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1dce0 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1dcf0 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1dd00 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1dd10 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1dd20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1dd30 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1dd40 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1dd50 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1dd60 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1dd70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1dd80 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1dd90 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1dda0 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1ddb0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1ddc0 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1ddd0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1dde0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1ddf0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1de00 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1de10 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1de20 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1de30 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1de40 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1de50 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1de60 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1de70 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1de80 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1de90 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1dea0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1deb0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1dec0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1ded0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1dee0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1def0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1df00 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1df10 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1df20 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1df30 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1df40 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e  e "%w" formattin
1df50 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65  g option is like
1df60 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68 61   "%q" except tha
1df70 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a  t it expects to.
1df80 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  ** be contained 
1df90 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75  within double-qu
1dfa0 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20  otes instead of 
1dfb0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61  single quotes, a
1dfc0 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73  nd it.** escapes
1dfd0 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74   the double-quot
1dfe0 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74  e character inst
1dff0 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c  ead of the singl
1e000 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61  e-quote.** chara
1e010 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77  cter.)^  The "%w
1e020 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1e030 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ion is intended 
1e040 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72  for safely inser
1e050 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e  ting.** table an
1e060 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69  d column names i
1e070 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65  nto a constructe
1e080 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  d SQL statement.
1e090 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
1e0a0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1e0b0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
1e0c0 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
1e0d0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
1e0e0 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
1e0f0 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
1e100 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
1e110 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
1e120 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1e130 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
1e140 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
1e150 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ^.*/.char *sqlit
1e160 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1e170 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
1e180 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1e190 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1e1a0 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
1e1b0 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1e1c0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1e1d0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63  t char*, ...);.c
1e1e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
1e1f0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1e200 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1e210 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1e220 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1e230 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1e240 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1e250 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1e260 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1e270 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1e280 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1e290 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1e2a0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1e2b0 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1e2c0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1e2d0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1e2e0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1e2f0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1e300 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1e310 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1e320 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1e330 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1e340 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1e350 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1e360 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1e370 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1e380 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1e390 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1e3a0 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1e3b0 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1e3c0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1e3d0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1e3e0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1e3f0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1e400 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1e410 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1e420 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1e430 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1e440 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1e450 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1e460 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1e470 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1e480 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1e490 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1e4a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1e4b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e4c0 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f  3_malloc64(N) ro
1e4d0 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74  utine works just
1e4e0 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33   like.** sqlite3
1e4f0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70  _malloc(N) excep
1e500 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75  t that N is an u
1e510 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69  nsigned 64-bit i
1e520 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1e530 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32  * of a signed 32
1e540 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  -bit integer..**
1e550 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1e560 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1e570 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1e580 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1e590 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1e5a0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1e5b0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1e5c0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1e5d0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1e5e0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1e5f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1e600 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1e610 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1e620 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1e630 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1e640 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1e650 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1e660 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1e670 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1e680 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1e690 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1e6a0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1e6b0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1e6c0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1e6d0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1e6e0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1e6f0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1e700 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1e710 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1e720 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1e730 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1e740 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1e750 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1e760 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1e770 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1e780 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1e790 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1e7a0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1e7b0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1e7c0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e7d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1e7e0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  lloc()..**.** ^T
1e7f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1e800 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  oc(X,N) interfac
1e810 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1e820 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1e830 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1e840 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61  n X to be at lea
1e850 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  st N bytes..** ^
1e860 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  If the X paramet
1e870 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1e880 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73  alloc(X,N).** is
1e890 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1e8a0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1e8b0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1e8c0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1e8d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a  ite3_malloc(N)..
1e8e0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72  ** ^If the N par
1e8f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1e900 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1e910 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1e920 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1e930 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1e940 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1e950 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1e960 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73  3_free(X)..** ^s
1e970 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1e980 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ,N) returns a po
1e990 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1e9a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1e9b0 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1e9c0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1e9d0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
1e9e0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76  ent memory is av
1e9f0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1ea00 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1ea10 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1ea20 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1ea30 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1ea40 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1ea50 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1ea60 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1ea70 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1ea80 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1ea90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1eaa0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1eab0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1eac0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1ead0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1eae0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
1eaf0 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c  d N is positive,
1eb00 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69   then the.** pri
1eb10 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1eb20 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1eb30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1eb40 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e  ealloc64(X,N) in
1eb50 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74  terfaces works t
1eb60 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
1eb70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1eb80 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1eb90 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73   is a 64-bit uns
1eba0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e  igned integer in
1ebb0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32  stead.** of a 32
1ebc0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1ebd0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58  ger..**.** ^If X
1ebe0 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   is a memory all
1ebf0 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73  ocation previous
1ec00 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
1ec10 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ec20 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
1ec30 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65  lloc64(), sqlite
1ec40 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20  3_realloc(), or 
1ec50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1ec60 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  4(), then.** sql
1ec70 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1ec80 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
1ec90 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c  f that memory al
1eca0 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65  location in byte
1ecb0 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  s..** ^The value
1ecc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1ecd0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69  ite3_msize(X) mi
1ece0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
1ecf0 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  an the number.**
1ed00 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73   of bytes reques
1ed10 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61  ted when X was a
1ed20 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58  llocated.  ^If X
1ed30 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1ed40 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  er then.** sqlit
1ed50 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1ed60 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20  rns zero.  If X 
1ed70 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68  points to someth
1ed80 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a  ing that is not.
1ed90 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  ** the beginning
1eda0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
1edb0 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20  ation, or if it 
1edc0 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d  points to a form
1edd0 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65  erly.** valid me
1ede0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1edf0 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65  that has now bee
1ee00 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68  n freed, then th
1ee10 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
1ee20 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1ee30 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  ) is undefined a
1ee40 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d  nd possibly harm
1ee50 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ful..**.** ^The 
1ee60 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1ee70 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1ee80 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  c(), sqlite3_rea
1ee90 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1eea0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61  e3_malloc64(), a
1eeb0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1eec0 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77  oc64().** is alw
1eed0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1eee0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1eef0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1ef00 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1ef10 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1ef20 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1ef30 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1ef40 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1ef50 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1ef60 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1ef70 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1ef80 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1ef90 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1efa0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1efb0 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1efc0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1efd0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1efe0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1eff0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1f000 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1f010 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1f020 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1f030 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1f040 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1f050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1f060 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1f070 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1f080 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1f090 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1f0a0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1f0b0 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1f0c0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1f0d0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1f0e0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1f0f0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1f100 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1f110 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1f120 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1f130 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1f140 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1f150 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1f160 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1f170 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1f180 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1f190 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1f1a0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1f1b0 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1f1c0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1f1d0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1f1e0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1f1f0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1f200 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1f210 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1f220 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1f230 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1f240 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1f250 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1f260 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1f270 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1f280 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1f290 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1f2a0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1f2b0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1f2c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f2d0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1f2e0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1f2f0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1f300 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1f310 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1f320 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1f330 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1f340 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1f350 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1f360 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1f370 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1f380 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1f390 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1f3a0 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
1f3b0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1f3c0 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69  loc64(sqlite3_ui
1f3d0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  nt64);.void *sql
1f3e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1f3f0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  d*, int);.void *
1f400 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1f410 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  4(void*, sqlite3
1f420 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  _uint64);.void s
1f430 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1f440 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74  *);.sqlite3_uint
1f450 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  64 sqlite3_msize
1f460 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1f470 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1f480 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1f490 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1f4a0 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1f4b0 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1f4c0 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1f4d0 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1f4e0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1f4f0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1f500 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1f510 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1f520 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1f530 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1f540 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1f550 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1f560 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1f570 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1f580 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1f590 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1f5a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1f5b0 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1f5c0 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1f5d0 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1f5e0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1f5f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1f600 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1f610 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1f620 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1f630 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1f640 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1f650 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1f660 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1f670 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1f680 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1f690 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1f6a0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1f6b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1f6c0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1f6d0 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1f6e0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1f6f0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1f700 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1f710 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1f720 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1f730 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1f740 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1f750 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1f760 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1f770 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1f780 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1f790 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1f7a0 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1f7b0 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1f7c0 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1f7d0 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1f7e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1f7f0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1f800 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1f810 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1f820 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1f830 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1f840 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1f850 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1f860 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1f870 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1f880 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1f890 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1f8a0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1f8b0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1f8c0 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
1f8d0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1f8e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1f8f0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1f900 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1f910 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1f920 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1f930 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1f940 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1f950 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1f960 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1f970 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1f980 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1f990 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1f9a0 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1f9b0 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1f9c0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1f9d0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1f9e0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1f9f0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1fa00 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1fa10 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1fa20 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1fa30 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1fa40 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1fa50 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1fa60 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1fa70 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1fa80 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1fa90 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1faa0 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1fab0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1fac0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1fad0 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1fae0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1faf0 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  er P..** ^The P 
1fb00 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
1fb10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1fb20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20  .**.** ^If this 
1fb30 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20  routine has not 
1fb40 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  been previously 
1fb50 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65  called or if the
1fb60 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c   previous.** cal
1fb70 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61  l had N less tha
1fb80 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20  n one or a NULL 
1fb90 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74  pointer for P, t
1fba0 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a  hen the PRNG is.
1fbb0 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  ** seeded using 
1fbc0 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
1fbd0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
1fbe0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1fbf0 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  of.** the defaul
1fc00 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1fc10 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74  object..** ^If t
1fc20 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
1fc30 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1fc40 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f   had an N of 1 o
1fc50 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20  r more and a.** 
1fc60 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20  non-NULL P then 
1fc70 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
1fc80 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
1fc90 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
1fca0 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
1fcb0 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
1fcc0 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
1fcd0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
1fce0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1fcf0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
1fd00 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
1fd10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1fd20 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
1fd30 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
1fd40 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
1fd50 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1fd60 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
1fd70 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
1fd80 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
1fd90 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1fda0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1fdb0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
1fdc0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1fdd0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
1fde0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fdf0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
1fe00 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
1fe10 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
1fe20 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
1fe30 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1fe40 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
1fe50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fe60 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
1fe70 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
1fe80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1fe90 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
1fea0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
1feb0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
1fec0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
1fed0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
1fee0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
1fef0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
1ff00 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
1ff10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ff20 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1ff30 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
1ff40 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
1ff50 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
1ff60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ff70 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
1ff80 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
1ff90 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
1ffa0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
1ffb0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
1ffc0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1ffd0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
1ffe0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1fff0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
20000 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
20010 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
20020 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
20030 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
20040 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
20050 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
20060 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
20070 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20080 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
20090 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
200a0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
200b0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
200c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
200d0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
200e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
200f0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
20100 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
20110 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
20120 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
20130 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
20140 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
20150 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
20160 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
20170 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
20180 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
20190 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
201a0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
201b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
201c0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
201d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
201e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
201f0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
20200 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
20210 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
20220 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
20230 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
20240 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
20250 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
20260 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
20270 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
20280 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
20290 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
202a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
202b0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
202c0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
202d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
202e0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
202f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
20300 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
20310 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
20320 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
20330 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
20340 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
20350 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
20360 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
20370 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
20380 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
20390 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
203a0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
203b0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
203c0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
203d0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
203e0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
203f0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
20400 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
20410 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
20420 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
20430 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
20440 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
20450 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
20460 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
20470 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
20480 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
20490 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
204a0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
204b0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
204c0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
204d0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
204e0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
204f0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
20500 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
20510 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
20520 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
20530 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
20540 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
20550 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
20560 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
20570 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
20580 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
20590 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
205a0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
205b0 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
205c0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
205d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
205e0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
205f0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
20600 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
20610 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
20620 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
20630 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
20640 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
20650 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
20660 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
20670 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
20680 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20690 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
206a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
206b0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
206c0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
206d0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
206e0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
206f0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
20700 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
20710 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
20720 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
20730 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
20740 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
20750 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
20760 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
20770 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
20780 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
20790 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
207a0 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
207b0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
207c0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
207d0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
207e0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
207f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
20800 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
20810 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
20820 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
20830 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
20840 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
20850 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
20860 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
20870 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
20880 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
20890 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
208a0 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
208b0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
208c0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
208d0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
208e0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
208f0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
20900 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
20910 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
20920 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
20930 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
20940 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
20950 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
20960 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
20970 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
20980 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
20990 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
209a0 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
209b0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
209c0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
209d0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
209e0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
209f0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
20a00 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
20a10 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
20a20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
20a30 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
20a40 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
20a50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
20a60 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
20a70 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
20a80 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
20a90 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
20aa0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
20ab0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
20ac0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
20ad0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
20ae0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
20af0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
20b00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
20b10 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
20b20 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
20b30 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
20b40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
20b50 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
20b60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20b70 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
20b80 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
20b90 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
20ba0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
20bb0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
20bc0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
20bd0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
20be0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
20bf0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
20c00 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
20c10 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
20c20 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
20c30 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
20c40 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
20c50 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
20c60 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
20c70 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
20c80 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
20c90 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
20ca0 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
20cb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
20cc0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
20cd0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
20ce0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20cf0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
20d00 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
20d10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
20d20 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
20d30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20d40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
20d50 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
20d60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
20d70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
20d80 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
20d90 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
20da0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
20db0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
20dc0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
20dd0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
20de0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
20df0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
20e00 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
20e10 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
20e20 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
20e30 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
20e40 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
20e50 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
20e60 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
20e70 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
20e80 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
20e90 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
20ea0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
20eb0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
20ec0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
20ed0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
20ee0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
20ef0 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
20f00 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
20f10 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
20f20 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
20f30 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
20f40 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
20f50 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
20f60 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
20f70 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
20f80 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
20f90 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
20fa0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
20fb0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
20fc0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
20fd0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
20fe0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
20ff0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
21000 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
21010 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
21020 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
21030 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
21040 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
21050 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
21060 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
21070 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65  s a [conflict re
21080 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a  solution mode].*
21090 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  * returned from 
210a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
210b0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
210c0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
210d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
210e0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
210f0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
21100 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
21110 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
21120 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
21130 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
21140 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
21150 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
21160 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
21170 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
21180 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
21190 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
211a0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
211b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
211c0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
211d0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
211e0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
211f0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
21200 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
21210 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
21220 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
21230 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
21240 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
21250 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
21260 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
21270 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
21280 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
21290 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
212a0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
212b0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
212c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
212d0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
212e0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
212f0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
21300 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
21310 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
21320 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
21330 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
21340 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
21350 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
21360 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
21370 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
21380 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
21390 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
213a0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
213b0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
213c0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
213d0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
213e0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
213f0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
21400 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
21410 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
21420 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
21430 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
21440 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
21450 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
21460 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
21470 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21480 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
21490 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
214a0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
214b0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
214c0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
214d0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
214e0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
214f0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
21500 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
21510 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
21520 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
21530 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21540 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21550 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
21560 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
21570 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
21580 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21590 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
215a0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
215b0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
215c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
215d0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
215e0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
215f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21600 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21610 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21620 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21630 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
21640 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
21650 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21660 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21670 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21680 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
21690 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
216a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
216b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
216c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
216d0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
216e0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
216f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21710 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
21720 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
21730 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
21740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21760 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
21770 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
21780 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
21790 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
217a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
217b0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
217c0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
217d0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
217e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
217f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21800 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
21810 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
21820 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21830 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21850 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
21860 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
21870 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
21880 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
218a0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
218b0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
218c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
218d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
218e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
218f0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
21900 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
21910 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
21920 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21940 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
21950 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
21960 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21970 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21980 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21990 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
219a0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
219b0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
219c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
219d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
219e0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
219f0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
21a00 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
21a10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21a20 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21a30 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
21a40 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
21a50 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
21a60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21a70 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
21a80 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
21a90 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
21aa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21ab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21ac0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
21ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
21ae0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21af0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21b00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21b10 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
21b20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
21b30 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
21b40 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
21b50 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
21b60 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
21b70 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
21b80 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21b90 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
21ba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21bb0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
21bc0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
21bd0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
21be0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21bf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21c00 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
21c10 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
21c20 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
21c30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21c50 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
21c60 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
21c70 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21c80 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
21c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21ca0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
21cb0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
21cc0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
21cd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21cf0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
21d00 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
21d10 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
21d20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21d40 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
21d50 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
21d60 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
21d70 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21d80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
21d90 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
21da0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
21db0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
21dc0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21dd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
21de0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
21df0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
21e00 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21e10 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21e20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21e30 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
21e40 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
21e50 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
21e60 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
21e70 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21e80 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
21e90 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
21ea0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
21eb0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
21ec0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
21ed0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
21ee0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
21ef0 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
21f00 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
21f10 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
21f20 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
21f30 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
21f40 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
21f50 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
21f60 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
21f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
21f80 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
21f90 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
21fa0 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45  SQLITE_RECURSIVE
21fb0 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20              33  
21fc0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
21fd0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21fe0 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41      */../*.** CA
21ff0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
22000 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
22010 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
22020 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
22030 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
22040 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20  are deprecated. 
22050 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
22060 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74  _trace_v2()] int
22070 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61  erface.** instea
22080 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65  d of the routine
22090 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65  s described here
220a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
220b0 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
220c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
220d0 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
220e0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
220f0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
22100 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
22110 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
22120 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
22130 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
22140 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
22150 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
22160 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
22170 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
22180 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
22190 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
221a0 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
221b0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
221c0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
221d0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
221e0 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
221f0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
22200 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
22210 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
22220 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
22230 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
22240 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
22250 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
22260 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
22270 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
22280 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
22290 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
222a0 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
222b0 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
222c0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
222d0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
222e0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
222f0 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  igger.)^.**.** T
22300 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
22310 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
22320 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
22330 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
22340 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e  limit.** the len
22350 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  gth of [bound pa
22360 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69  rameter] expansi
22370 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74  on in the output
22380 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63   of sqlite3_trac
22390 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e()..**.** ^The 
223a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
223b0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
223c0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
223d0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
223e0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
223f0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
22400 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
22410 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
22420 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
22430 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
22440 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
22450 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
22460 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
22470 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
22480 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
22490 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
224a0 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
224b0 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
224c0 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
224d0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
224e0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
224f0 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
22500 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
22510 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
22520 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
22530 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
22540 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
22550 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
22560 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
22570 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
22580 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
22590 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
225a0 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
225b0 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
225c0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
225d0 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
225e0 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
225f0 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
22600 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
22610 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
22620 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
22630 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
22640 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
22650 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a  trace(sqlite3*,.
22660 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29     void(*xTrace)
22670 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
22680 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
22690 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
226a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
226b0 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
226c0 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
226d0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
226e0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
226f0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
22700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
22710 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f  L Trace Event Co
22720 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
22730 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a   SQLITE_TRACE.**
22740 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
22750 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61  nts identify cla
22760 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74  sses of events t
22770 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74  hat can be monit
22780 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ored.** using th
22790 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  e [sqlite3_trace
227a0 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c  _v2()] tracing l
227b0 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72 64  ogic.  The third
227c0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
227d0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
227e0 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64  2()] is an OR-ed
227f0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20   combination of 
22800 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a  one or more of.*
22810 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
22820 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65  constants.  ^The
22830 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
22840 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
22850 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20  lback.** is one 
22860 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
22870 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
22880 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f  * New tracing co
22890 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61  nstants may be a
228a0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
228b0 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  eleases..**.** ^
228c0 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  A trace callback
228d0 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65   has four argume
228e0 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54  nts: xCallback(T
228f0 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65  ,C,P,X)..** ^The
22900 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f   T argument is o
22910 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ne of the intege
22920 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f  r type codes abo
22930 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72  ve..** ^The C ar
22940 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79  gument is a copy
22950 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20   of the context 
22960 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
22970 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  n as the.** four
22980 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
22990 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
229a0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e  ()]..** The P an
229b0 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72  d X arguments ar
229c0 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65  e pointers whose
229d0 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64   meanings depend
229e0 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c   on T..**.** <dl
229f0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  >.** [[SQLITE_TR
22a00 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53  ACE_STMT]] <dt>S
22a10 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
22a20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
22a30 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54   SQLITE_TRACE_ST
22a40 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  MT callback is i
22a50 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72  nvoked when a pr
22a60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22a70 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73  .** first begins
22a80 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73   running and pos
22a90 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74  sibly at other t
22aa0 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a  imes during the.
22ab0 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  ** execution of 
22ac0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
22ad0 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20  tement, such as 
22ae0 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66 20  at the start of 
22af0 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20  each.** trigger 
22b00 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65  subprogram. ^The
22b10 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
22b20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
22b30 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
22b40 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20  tement]. ^The X 
22b50 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
22b60 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
22b70 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  g which.** is th
22b80 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c  e unexpanded SQL
22b90 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72 65   text of the pre
22ba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
22bb0 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e  or an SQL commen
22bc0 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  t .** that indic
22bd0 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74  ates the invocat
22be0 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72  ion of a trigger
22bf0 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  .  ^The callback
22c00 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20   can compute.** 
22c10 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74 68  the same text th
22c20 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65  at would have be
22c30 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  en returned by t
22c40 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
22c50 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69  e3_trace()].** i
22c60 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69 6e  nterface by usin
22c70 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74  g the X argument
22c80 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77   when X begins w
22c90 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76  ith "--" and inv
22ca0 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  oking.** [sqlite
22cb0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
22cc0 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  )] otherwise..**
22cd0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
22ce0 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74  CE_PROFILE]] <dt
22cf0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52  >SQLITE_TRACE_PR
22d00 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OFILE</dt>.** <d
22d10 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
22d20 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62  CE_PROFILE callb
22d30 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70  ack provides app
22d40 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73  roximately the s
22d50 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ame.** informati
22d60 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64 65  on as is provide
22d70 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
22d80 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c  3_profile()] cal
22d90 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50  lback..** ^The P
22da0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
22db0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70  ointer to the [p
22dc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22dd0 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20  t] and the.** X 
22de0 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
22df0 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65  to a 64-bit inte
22e00 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68 65  ger which is the
22e10 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a   estimated of.**
22e20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e   the number of n
22e30 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74  anosecond that t
22e40 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
22e50 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
22e60 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54  n..** ^The SQLIT
22e70 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
22e80 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
22e90 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74 61  ked when the sta
22ea0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
22eb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
22ec0 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e  TRACE_ROW]] <dt>
22ed0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
22ee0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
22ef0 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f   SQLITE_TRACE_RO
22f00 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  W callback is in
22f10 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
22f20 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
22f30 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73  tement generates
22f40 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
22f50 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54   result.  .** ^T
22f60 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
22f70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
22f80 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
22f90 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a  ement] and the.*
22fa0 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20  * X argument is 
22fb0 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  unused..**.** [[
22fc0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
22fd0 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  SE]] <dt>SQLITE_
22fe0 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e  TRACE_CLOSE</dt>
22ff0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
23000 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63  TE_TRACE_CLOSE c
23010 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
23020 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  ed when a databa
23030 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
23040 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65   closes..** ^The
23050 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
23060 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
23070 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23080 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  tion] object.** 
23090 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d 65  and the X argume
230a0 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
230b0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
230c0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  e SQLITE_TRACE_S
230d0 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a 23  TMT       0x01.#
230e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
230f0 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30  ACE_PROFILE    0
23100 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x02.#define SQLI
23110 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20  TE_TRACE_ROW    
23120 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65      0x04.#define
23130 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c   SQLITE_TRACE_CL
23140 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f  OSE      0x08../
23150 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
23160 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a  QL Trace Hook.**
23170 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
23180 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23190 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d  te3_trace_v2(D,M
231a0 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
231b0 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61 63  registers a trac
231c0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
231d0 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74  nction X against
231e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
231f0 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20  ction] D, using 
23200 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a  property mask M.
23210 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70  ** and context p
23220 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74  ointer P.  ^If t
23230 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73  he X callback is
23240 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74  .** NULL or if t
23250 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72  he M mask is zer
23260 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20  o, then tracing 
23270 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68  is disabled.  Th
23280 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20  e.** M argument 
23290 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69  should be the bi
232a0 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62  twise OR-ed comb
232b0 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65  ination of.** ze
232c0 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49  ro or more [SQLI
232d0 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61  TE_TRACE] consta
232e0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  nts..**.** ^Each
232f0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
23300 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
23310 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  or sqlite3_trace
23320 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73 20  _v2() overrides 
23330 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e  .** (cancels) an
23340 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f  y prior calls to
23350 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
23360 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
23370 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e_v2()..**.** ^T
23380 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73  he X callback is
23390 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
233a0 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65  r any of the eve
233b0 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20 62  nts identified b
233c0 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63  y .** mask M occ
233d0 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65  ur.  ^The intege
233e0 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  r return value f
233f0 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  rom the callback
23400 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a   is currently.**
23410 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68   ignored, though
23420 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65   this may change
23430 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
23440 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a  ses.  Callback.*
23450 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
23460 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  s should return 
23470 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66  zero to ensure f
23480 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c  uture compatibil
23490 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72  ity..**.** ^A tr
234a0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
234b0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75  invoked with fou
234c0 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c  r arguments: cal
234d0 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a  lback(T,C,P,X)..
234e0 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65  ** ^The T argume
234f0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  nt is one of the
23500 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a   [SQLITE_TRACE].
23510 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20  ** constants to 
23520 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68 65  indicate why the
23530 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e   callback was in
23540 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43  voked..** ^The C
23550 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63   argument is a c
23560 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
23570 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54  xt pointer..** T
23580 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d  he P and X argum
23590 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72  ents are pointer
235a0 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73  s whose meanings
235b0 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a   depend on T..**
235c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
235d0 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72  trace_v2() inter
235e0 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
235f0 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20   to replace the 
23600 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
23610 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72  aces [sqlite3_tr
23620 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ace()] and [sqli
23630 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20  te3_profile()], 
23640 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a  both of which.**
23650 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
23660 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23670 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69  trace_v2(.  sqli
23680 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64  te3*,.  unsigned
23690 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78   uMask,.  int(*x
236a0 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e  Callback)(unsign
236b0 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76  ed,void*,void*,v
236c0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  oid*),.  void *p
236d0 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Ctx.);../*.** CA
236e0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
236f0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
23700 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
23710 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
23720 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
23730 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
23740 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
23750 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
23760 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
23770 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
23780 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
23790 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
237a0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
237b0 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
237c0 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
237d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
237e0 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
237f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
23800 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
23810 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
23820 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
23830 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
23840 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
23850 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
23860 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
23870 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
23880 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
23890 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
238a0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
238b0 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
238c0 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
238d0 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
238e0 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
238f0 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
23900 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
23910 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
23920 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
23930 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
23940 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
23950 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
23960 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
23970 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
23980 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
23990 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
239a0 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
239b0 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
239c0 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
239d0 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
239e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
239f0 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
23a00 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23a10 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
23a20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
23a30 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
23a40 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
23a50 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
23a60 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
23a70 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
23a80 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
23a90 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
23aa0 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
23ab0 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
23ac0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
23ad0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
23ae0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
23af0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
23b00 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
23b10 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
23b20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
23b30 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
23b40 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
23b50 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
23b60 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
23b70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
23b80 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
23b90 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
23ba0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
23bb0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
23bc0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
23bd0 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
23be0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
23bf0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
23c00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23c10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
23c20 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
23c30 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
23c40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
23c50 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
23c60 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
23c70 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
23c80 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
23c90 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
23ca0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
23cb0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
23cc0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
23cd0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
23ce0 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
23cf0 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43   Connection.** C
23d00 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  ONSTRUCTOR: sqli
23d10 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
23d20 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
23d30 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
23d40 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
23d50 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
23d60 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
23d70 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
23d80 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
23d90 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
23da0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
23db0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
23dc0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
23dd0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
23de0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
23df0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
23e00 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
23e10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23e20 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
23e30 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
23e40 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
23e50 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
23e60 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
23e70 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
23e80 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
23e90 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
23ea0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
23eb0 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
23ec0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
23ed0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
23ee0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
23ef0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
23f00 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
23f10 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
23f20 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
23f30 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
23f40 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
23f50 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
23f60 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
23f70 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
23f80 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
23f90 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
23fa0 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
23fb0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
23fc0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
23fd0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
23fe0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
23ff0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
24000 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
24010 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
24020 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
24030 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
24040 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
24050 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24060 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
24070 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
24080 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54  oding will be UT
24090 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65  F-8 for database
240a0 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
240b0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
240c0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
240d0 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65  n_v2().  ^The de
240e0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
240f0 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20  or databases.** 
24100 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71  created using sq
24110 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77  lite3_open16() w
24120 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e  ill be UTF-16 in
24130 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
24140 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68   order..**.** Wh
24150 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
24160 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
24170 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
24180 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
24190 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
241a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
241b0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
241c0 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
241d0 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
241e0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
241f0 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
24200 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
24210 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
24220 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24230 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
24240 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
24250 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
24260 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
24270 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
24280 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
24290 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
242a0 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
242b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
242c0 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
242d0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
242e0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
242f0 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
24300 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
24310 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
24320 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
24330 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
24340 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
24350 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
24360 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
24370 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
24380 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
24390 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
243a0 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
243b0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
243c0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
243d0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
243e0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
243f0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
24400 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
24410 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
24420 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
24430 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
24440 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
24450 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
24460 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
24470 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
24480 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
24490 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
244a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
244b0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
244c0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
244d0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
244e0 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
244f0 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
24500 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
24510 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
24520 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
24530 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
24540 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
24550 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
24560 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
24570 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
24580 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
24590 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
245a0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
245b0 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
245c0 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
245d0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
245e0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
245f0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
24600 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
24610 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
24620 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
24630 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
24640 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
24650 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
24660 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24670 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
24680 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
24690 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
246a0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
246b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
246c0 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
246d0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
246e0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
246f0 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
24700 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
24710 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
24720 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
24730 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
24740 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
24750 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
24760 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
24770 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
24780 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
24790 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
247a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
247b0 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
247c0 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
247d0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
247e0 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
247f0 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
24800 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
24810 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
24820 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
24830 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
24840 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
24850 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
24860 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
24870 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24880 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
24890 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
248a0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
248b0 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
248c0 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
248d0 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
248e0 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
248f0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
24900 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
24910 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
24920 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
24930 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24940 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
24950 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
24960 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
24970 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
24980 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
24990 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
249a0 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
249b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
249c0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
249d0 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
249e0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
249f0 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
24a00 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
24a10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
24a20 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
24a30 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
24a40 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
24a50 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
24a60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
24a70 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
24a80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24a90 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
24aa0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
24ab0 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
24ac0 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
24ad0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
24ae0 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
24af0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
24b00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
24b10 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
24b20 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
24b30 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
24b40 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
24b50 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
24b60 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
24b70 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
24b80 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
24b90 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
24ba0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
24bb0 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
24bc0 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
24bd0 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
24be0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
24bf0 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
24c00 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
24c10 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
24c20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24c30 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
24c40 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
24c50 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
24c60 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
24c70 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
24c80 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
24c90 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
24ca0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
24cb0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
24cc0 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
24cd0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
24ce0 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
24cf0 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
24d00 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
24d10 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
24d20 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
24d30 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
24d40 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
24d50 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
24d60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
24d70 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
24d80 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
24d90 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
24da0 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
24db0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
24dc0 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
24dd0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
24de0 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
24df0 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
24e00 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
24e10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24e20 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
24e30 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
24e40 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
24e50 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
24e60 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
24e70 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
24e80 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
24e90 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
24ea0 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
24eb0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
24ec0 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
24ed0 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
24ee0 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
24ef0 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
24f00 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
24f10 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
24f20 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
24f30 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
24f40 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
24f50 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
24f60 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
24f70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
24f80 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
24f90 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
24fa0 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
24fb0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
24fc0 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
24fd0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
24fe0 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
24ff0 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
25000 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
25010 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
25020 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
25030 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
25040 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
25050 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
25060 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
25070 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
25080 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
25090 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
250a0 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
250b0 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
250c0 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
250d0 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
250e0 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
250f0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
25100 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
25110 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
25120 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
25130 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
25140 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
25150 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
25160 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
25170 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
25180 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
25190 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
251a0 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
251b0 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
251c0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
251d0 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
251e0 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
251f0 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
25200 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
25210 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
25220 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
25230 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
25240 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
25250 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
25260 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
25270 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
25280 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
25290 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
252a0 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
252b0 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
252c0 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
252d0 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
252e0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
252f0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
25300 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
25310 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
25320 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
25330 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
25340 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
25350 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
25360 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
25370 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
25380 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
25390 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
253a0 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
253b0 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
253c0 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
253d0 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
253e0 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
253f0 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
25400 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
25410 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
25420 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
25430 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
25440 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
25450 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
25460 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
25470 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
25480 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
25490 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
254a0 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
254b0 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
254c0 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
254d0 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
254e0 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
254f0 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
25500 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
25510 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
25520 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
25530 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
25540 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
25550 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
25560 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
25570 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
25580 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
25590 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
255a0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
255b0 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
255c0 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
255d0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
255e0 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
255f0 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
25600 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
25610 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
25620 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
25630 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
25640 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
25650 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
25660 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
25670 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
25680 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
25690 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
256a0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
256b0 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
256c0 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
256d0 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
256e0 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
256f0 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
25700 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
25710 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
25720 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
25730 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
25740 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
25750 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
25760 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
25770 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
25780 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
25790 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
257a0 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
257b0 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
257c0 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
257d0 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
257e0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
257f0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
25800 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
25810 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
25820 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
25830 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
25840 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
25850 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
25860 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
25870 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
25880 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
25890 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
258a0 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
258b0 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
258c0 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
258d0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
258e0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
258f0 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
25900 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
25910 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
25920 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
25930 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
25940 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
25950 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
25960 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
25970 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
25980 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
25990 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
259a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
259b0 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
259c0 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
259d0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
259e0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
259f0 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
25a00 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
25a10 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
25a20 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
25a30 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
25a40 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
25a50 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
25a60 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
25a70 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
25a80 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
25a90 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
25aa0 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
25ab0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
25ac0 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
25ad0 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
25ae0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
25af0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
25b00 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
25b10 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
25b20 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
25b30 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
25b40 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
25b50 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
25b60 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
25b70 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
25b80 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
25b90 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
25ba0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
25bb0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
25bc0 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
25bd0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
25be0 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
25bf0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
25c00 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
25c10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
25c20 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
25c30 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
25c40 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
25c50 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
25c60 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
25c70 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
25c80 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
25c90 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
25ca0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
25cb0 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
25cc0 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
25cd0 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
25ce0 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
25cf0 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
25d00 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
25d10 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
25d20 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
25d30 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
25d40 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
25d50 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
25d60 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
25d70 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
25d80 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
25d90 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
25da0 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
25db0 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
25dc0 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
25dd0 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
25de0 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
25df0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
25e00 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
25e10 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
25e20 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
25e30 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
25e40 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
25e50 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
25e60 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
25e70 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
25e80 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
25e90 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
25ea0 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
25eb0 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
25ec0 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
25ed0 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
25ee0 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
25ef0 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
25f00 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
25f10 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
25f20 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
25f30 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
25f40 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
25f50 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
25f60 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
25f70 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
25f80 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
25f90 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
25fa0 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
25fb0 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
25fc0 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
25fd0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
25fe0 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
25ff0 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
26000 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
26010 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
26020 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
26030 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
26040 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
26050 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
26060 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
26070 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
26080 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
26090 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
260a0 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
260b0 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
260c0 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
260d0 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
260e0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
260f0 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
26100 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
26110 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
26120 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
26130 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
26140 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
26150 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
26160 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
26170 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
26180 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
26190 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
261a0 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
261b0 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
261c0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
261d0 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
261e0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
261f0 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
26200 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
26210 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
26220 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
26230 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
26240 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
26250 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
26260 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
26270 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
26280 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
26290 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
262a0 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
262b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
262c0 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
262d0 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
262e0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
262f0 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
26300 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
26310 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
26320 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
26330 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
26340 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
26350 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
26360 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
26370 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
26380 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
26390 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
263a0 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
263b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
263c0 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
263d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
263e0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
263f0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
26400 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
26410 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
26420 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26430 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
26440 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
26450 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
26460 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
26470 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
26480 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26490 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
264a0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
264b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
264c0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
264d0 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
264e0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
264f0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26500 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
26510 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
26520 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
26530 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
26540 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
26550 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
26560 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
26570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
26580 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
26590 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
265a0 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
265b0 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
265c0 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
265d0 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
265e0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
265f0 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
26600 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
26610 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
26620 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
26630 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
26640 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
26650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
26660 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
26670 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
26680 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
26690 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
266a0 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
266b0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
266c0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
266d0 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
266e0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
266f0 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
26700 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
26710 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
26720 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
26730 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
26740 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
26750 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
26760 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
26770 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
26780 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
26790 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
267a0 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
267b0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
267c0 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
267d0 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
267e0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
267f0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
26800 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
26810 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
26820 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
26830 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
26840 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
26850 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
26860 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
26870 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26880 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
26890 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
268a0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
268b0 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
268c0 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
268d0 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
268e0 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
268f0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
26900 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
26910 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
26920 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
26930 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
26940 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
26950 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
26960 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
26970 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26980 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
26990 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
269a0 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
269b0 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
269c0 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
269d0 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
269e0 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
269f0 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
26a00 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
26a10 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
26a20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
26a30 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
26a40 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
26a50 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
26a60 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
26a70 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26a80 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
26a90 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
26aa0 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
26ab0 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
26ac0 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
26ad0 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
26ae0 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
26af0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
26b00 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
26b10 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
26b20 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
26b30 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
26b40 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
26b50 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
26b60 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
26b70 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
26b80 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
26b90 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
26ba0 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
26bb0 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
26bc0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
26bd0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
26be0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
26bf0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
26c00 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
26c10 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
26c20 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
26c30 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
26c40 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
26c50 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
26c60 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
26c70 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
26c80 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
26c90 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
26ca0 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
26cb0 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
26cc0 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
26cd0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
26ce0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26cf0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
26d00 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
26d10 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
26d20 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
26d30 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
26d40 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
26d50 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
26d60 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
26d70 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
26d80 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
26d90 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
26da0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26db0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
26dc0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
26dd0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
26de0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
26df0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
26e00 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
26e10 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
26e20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
26e30 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
26e40 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
26e50 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
26e60 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
26e70 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
26e80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26e90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
26ea0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
26eb0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26ec0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
26ed0 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
26ee0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
26ef0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
26f00 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
26f10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
26f20 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
26f30 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
26f40 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
26f50 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
26f60 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
26f70 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
26f80 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
26f90 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
26fa0 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
26fb0 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
26fc0 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
26fd0 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
26fe0 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
26ff0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
27000 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
27010 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
27020 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
27030 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
27040 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
27050 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
27060 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
27070 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
27080 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
27090 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
270a0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
270b0 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
270c0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
270d0 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
270e0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
270f0 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
27100 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
27110 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
27120 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
27130 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
27140 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
27150 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
27160 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
27170 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
27180 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
27190 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
271a0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
271b0 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
271c0 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
271d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
271e0 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
271f0 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
27200 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
27210 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
27220 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
27230 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
27240 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
27250 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
27260 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
27270 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
27280 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
27290 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
272a0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
272b0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
272c0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
272d0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
272e0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
272f0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
27300 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
27310 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
27320 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
27330 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
27340 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
27350 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
27360 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
27370 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
27380 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
27390 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
273a0 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
273b0 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
273c0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
273d0 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
273e0 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
273f0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
27400 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
27410 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
27420 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
27430 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
27440 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
27450 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
27460 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
27470 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
27480 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
27490 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
274a0 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
274b0 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
274c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
274d0 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
274e0 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
274f0 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
27500 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
27510 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
27520 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
27530 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
27540 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27550 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
27560 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
27570 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
27580 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
27590 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
275a0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
275b0 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
275c0 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
275d0 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
275e0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
275f0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
27600 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
27610 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
27620 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
27630 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
27640 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
27650 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27660 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
27670 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
27680 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27690 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
276a0 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
276b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
276c0 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
276d0 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
276e0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
276f0 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
27700 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
27710 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
27720 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
27730 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
27740 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
27750 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
27760 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e  esirable..*/.con
27770 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27780 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
27790 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
277a0 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
277b0 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
277c0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
277d0 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
277e0 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
277f0 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
27800 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
27810 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
27820 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
27830 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
27840 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
27850 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
27860 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
27870 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
27880 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
27890 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
278a0 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74  ost recent sqlit
278b0 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
278c0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
278d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
278e0 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64  ection] D failed
278f0 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
27900 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e  e3_errcode(D) in
27910 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
27920 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
27930 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
27940 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
27950 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a   code] for that.
27960 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20  ** API call..** 
27970 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
27980 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20  nt API call was 
27990 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74  successful,.** t
279a0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
279b0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
279c0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
279d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68  ndefined..** ^Th
279e0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
279f0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
27a00 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
27a10 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
27a20 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
27a30 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
27a40 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27a50 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
27a60 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27a70 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
27a80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
27a90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
27aa0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
27ab0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
27ac0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
27ad0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
27ae0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
27af0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
27b00 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
27b10 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
27b20 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
27b30 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
27b40 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
27b50 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
27b60 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
27b70 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
27b80 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
27b90 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
27ba0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
27bb0 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
27bc0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
27bd0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
27be0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
27bf0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
27c00 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
27c10 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
27c20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27c30 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
27c40 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
27c50 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
27c60 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
27c70 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
27c80 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
27c90 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
27ca0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
27cb0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
27cc0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
27cd0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
27ce0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
27cf0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
27d00 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
27d10 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
27d20 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
27d30 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
27d40 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
27d50 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
27d60 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
27d70 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
27d80 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
27d90 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
27da0 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
27db0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
27dc0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
27dd0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
27de0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
27df0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
27e00 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
27e10 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
27e20 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
27e30 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
27e40 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
27e50 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
27e60 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
27e70 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
27e80 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
27e90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
27ea0 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
27eb0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
27ec0 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
27ed0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
27ee0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
27ef0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
27f00 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
27f10 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
27f20 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
27f30 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
27f40 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
27f50 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
27f60 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
27f70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
27f80 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
27f90 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
27fa0 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
27fb0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
27fc0 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
27fd0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
27fe0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
27ff0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
28000 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
28010 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
28020 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
28030 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28040 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
28050 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
28060 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
28070 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
28080 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28090 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
280a0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
280b0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
280c0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
280d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
280e0 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
280f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28100 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
28110 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
28120 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
28130 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
28140 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28150 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
28160 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
28170 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
28180 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
28190 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61  ement that.** ha
281a0 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20  s been compiled 
281b0 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d  into binary form
281c0 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f   and is ready to
281d0 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a   be evaluated..*
281e0 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61  *.** Think of ea
281f0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
28200 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63   as a separate c
28210 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e  omputer program.
28220 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61    The.** origina
28230 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f  l SQL text is so
28240 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72  urce code.  A pr
28250 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28260 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74   object .** is t
28270 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65  he compiled obje
28280 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51  ct code.  All SQ
28290 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  L must be conver
282a0 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72  ted into a.** pr
282b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
282c0 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62   before it can b
282d0 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  e run..**.** The
282e0 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61   life-cycle of a
282f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28300 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c  ent object usual
28310 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69  ly goes like thi
28320 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
28330 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
28340 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28350 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  ent object using
28360 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28370 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e  e_v2()]..** <li>
28380 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
28390 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69  [parameters] usi
283a0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
283b0 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
283c0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
283d0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
283e0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
283f0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
28400 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
28410 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset 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 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
28440 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
28450 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
28460 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
28470 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
28480 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
28490 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
284a0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
284b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
284c0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65  ** </ol>.*/.type
284d0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
284e0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
284f0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
28500 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
28510 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44  Limits.** METHOD
28520 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
28530 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
28540 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
28550 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
28560 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
28570 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
28580 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
28590 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
285a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
285b0 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
285c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
285d0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
285e0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
285f0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
28600 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
28610 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
28620 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
28630 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
28640 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
28650 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
28660 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
28670 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
28680 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
28690 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
286a0 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
286b0 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
286c0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
286d0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
286e0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
286f0 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
28700 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
28710 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
28720 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
28730 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
28740 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
28750 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
28760 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
28770 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
28780 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
28790 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
287a0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
287b0 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
287c0 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
287d0 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
287e0 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
287f0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
28800 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
28810 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
28820 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
28830 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
28840 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
28850 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
28860 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
28870 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
28880 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
28890 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
288a0 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
288b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
288c0 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
288d0 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
288e0 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
288f0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
28900 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
28910 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
28920 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
28930 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
28940 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
28950 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
28960 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
28970 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
28980 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
28990 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
289a0 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
289b0 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
289c0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
289d0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
289e0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
289f0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
28a00 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
28a10 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
28a20 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
28a30 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
28a40 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
28a50 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
28a60 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
28a70 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
28a80 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
28a90 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
28aa0 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
28ab0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
28ac0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
28ad0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
28ae0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
28af0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
28b00 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
28b10 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
28b20 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
28b30 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
28b40 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
28b50 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
28b60 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
28b70 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
28b80 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
28b90 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
28ba0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
28bb0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
28bc0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
28bd0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
28be0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
28bf0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
28c00 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
28c10 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
28c20 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
28c30 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
28c40 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
28c50 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
28c60 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
28c70 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
28c80 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
28c90 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
28ca0 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
28cb0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
28cc0 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
28cd0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
28ce0 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
28cf0 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
28d00 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
28d10 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
28d20 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
28d30 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
28d40 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
28d50 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
28d60 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
28d70 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
28d80 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
28d90 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
28da0 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
28db0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
28dc0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
28dd0 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
28de0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
28df0 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
28e00 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
28e10 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
28e20 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
28e30 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
28e40 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
28e50 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
28e60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28e70 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
28e80 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
28e90 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
28ea0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
28eb0 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
28ec0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
28ed0 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
28ee0 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
28ef0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
28f00 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
28f10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
28f20 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
28f30 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
28f40 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
28f50 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
28f60 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
28f70 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28f80 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
28f90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
28fa0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
28fb0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
28fc0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
28fd0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
28fe0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
28ff0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
29000 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
29010 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29020 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
29030 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
29040 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
29050 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
29060 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
29070 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
29080 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
29090 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
290a0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
290b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
290c0 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
290d0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
290e0 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
290f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29100 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
29110 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
29120 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
29130 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
29140 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29150 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
29160 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
29170 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
29180 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
29190 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
291a0 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
291b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
291c0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
291d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
291e0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
291f0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
29200 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
29210 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
29220 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
29230 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
29240 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
29250 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
29260 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
29270 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
29280 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
29290 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
292a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
292b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
292c0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
292d0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
292e0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
292f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29300 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
29310 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
29320 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
29330 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29340 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
29350 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29360 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
29370 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29380 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
29390 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
293a0 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
293b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
293c0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
293d0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
293e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
293f0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29400 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
29410 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
29420 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
29430 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
29440 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
29450 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
29460 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
29470 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29480 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
29490 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
294a0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
294b0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
294c0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
294d0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
294e0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
294f0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
29500 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
29510 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
29520 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
29530 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
29540 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
29550 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29560 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
29570 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
29580 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
29590 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
295a0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
295b0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
295c0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
295d0 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
295e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
295f0 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
29600 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
29610 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
29620 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29630 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
29640 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
29650 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
29660 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
29670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29680 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
29690 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
296a0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
296b0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
296c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
296d0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
296e0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
296f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
29700 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
29710 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
29720 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
29730 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
29740 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
29750 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
29760 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
29770 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
29780 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
29790 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
297a0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
297b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
297c0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
297d0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
297e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
297f0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
29800 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
29810 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29820 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
29830 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
29840 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29850 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
29860 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
29870 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29880 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
29890 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
298a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
298b0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
298c0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
298d0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
298e0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
298f0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
29900 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
29910 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
29920 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
29930 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
29940 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
29950 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
29960 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
29970 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
29980 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
29990 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
299a0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
299b0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
299c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
299d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
299e0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
299f0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
29a00 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
29a10 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
29a20 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
29a30 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
29a40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29a50 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
29a60 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
29a70 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
29a80 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
29a90 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
29aa0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
29ab0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
29ac0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
29ad0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
29ae0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
29af0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
29b00 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
29b10 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
29b20 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
29b30 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
29b40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
29b50 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
29b60 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
29b70 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
29b80 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
29b90 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
29ba0 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
29bb0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
29bc0 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
29bd0 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
29be0 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
29bf0 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
29c00 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
29c10 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
29c20 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
29c30 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
29c40 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
29c50 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
29c60 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
29c70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
29c80 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
29c90 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
29ca0 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
29cb0 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
29cc0 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
29cd0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
29ce0 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
29cf0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
29d00 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
29d10 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
29d20 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
29d30 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
29d40 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
29d50 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
29d60 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
29d70 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
29d80 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
29d90 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
29da0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
29db0 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
29dc0 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
29dd0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
29de0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
29df0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
29e00 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
29e10 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
29e20 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
29e30 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
29e40 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
29e50 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
29e60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29e70 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
29e80 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
29e90 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
29ea0 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
29eb0 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
29ec0 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
29ed0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
29ee0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
29ef0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
29f00 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
29f10 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
29f20 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
29f30 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
29f40 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
29f50 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
29f60 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
29f70 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
29f80 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
29f90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
29fa0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
29fb0 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
29fc0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
29fd0 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
29fe0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
29ff0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
2a000 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
2a010 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
2a020 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
2a030 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2a040 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
2a050 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2a060 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2a070 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
2a080 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
2a090 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a0a0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
2a0b0 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
2a0c0 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
2a0d0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
2a0e0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
2a0f0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
2a100 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
2a110 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
2a120 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
2a130 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
2a140 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
2a150 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
2a160 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a170 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
2a180 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
2a190 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
2a1a0 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
2a1b0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
2a1c0 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
2a1d0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
2a1e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
2a1f0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
2a200 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
2a210 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
2a220 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
2a230 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
2a240 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
2a250 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
2a260 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
2a270 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
2a280 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
2a290 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
2a2a0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
2a2b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2a2c0 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
2a2d0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
2a2e0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
2a2f0 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
2a300 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
2a310 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
2a320 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
2a330 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
2a340 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
2a350 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
2a360 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
2a370 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
2a380 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
2a390 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
2a3a0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
2a3b0 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
2a3c0 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
2a3d0 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
2a3e0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
2a3f0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
2a400 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
2a410 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2a420 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
2a430 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
2a440 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
2a450 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
2a460 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a470 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
2a480 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
2a490 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
2a4a0 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
2a4b0 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
2a4c0 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
2a4d0 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
2a4e0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
2a4f0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
2a500 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
2a510 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
2a520 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
2a530 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
2a540 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2a550 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
2a560 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
2a570 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
2a580 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
2a590 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
2a5a0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
2a5b0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2a5c0 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
2a5d0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
2a5e0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
2a5f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
2a600 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
2a610 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
2a620 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
2a630 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
2a640 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
2a650 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
2a660 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
2a670 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
2a680 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
2a690 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
2a6a0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
2a6b0 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
2a6c0 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
2a6d0 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
2a6e0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
2a6f0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
2a700 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
2a710 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2a720 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
2a730 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
2a740 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
2a750 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
2a760 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
2a770 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2a780 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
2a790 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
2a7a0 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
2a7b0 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
2a7c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2a7d0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
2a7e0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
2a7f0 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
2a800 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
2a810 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2a820 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2a830 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a840 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2a850 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2a860 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2a870 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2a880 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2a890 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2a8a0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2a8b0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2a8c0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2a8d0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2a8e0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2a8f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2a900 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2a910 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2a920 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2a930 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2a940 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a950 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2a960 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2a970 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2a980 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2a990 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2a9a0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2a9b0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2a9c0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2a9d0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2a9e0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2a9f0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2aa00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2aa10 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2aa20 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2aa30 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2aa40 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2aa50 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2aa60 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2aa70 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2aa80 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2aa90 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
2aaa0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2aab0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2aac0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2aad0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2aae0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2aaf0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2ab00 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2ab10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2ab20 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2ab30 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2ab40 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2ab50 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2ab60 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2ab70 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2ab80 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2ab90 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2aba0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2abb0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2abc0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2abd0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
2abe0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2abf0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2ac00 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2ac10 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2ac20 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2ac30 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2ac40 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2ac50 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2ac60 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2ac70 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2ac80 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2ac90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2aca0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2acb0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2acc0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2acd0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2ace0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2acf0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2ad00 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
2ad10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2ad20 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
2ad30 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
2ad40 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ad50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ad60 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  e3_sql(P) interf
2ad70 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2ad80 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20  inter to a copy 
2ad90 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20  of the UTF-8.** 
2ada0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
2adb0 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65   create [prepare
2adc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69  d statement] P i
2add0 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74  f P was.** creat
2ade0 65 64 20 62 79 20 65 69 74 68 65 72 20 5b 73 71  ed by either [sq
2adf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ae00 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2ae10 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2ae20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ae30 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2ae40 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ae50 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2ae60 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  a UTF-8.** strin
2ae70 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
2ae80 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65   SQL text of pre
2ae90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2aea0 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64  P with.** [bound
2aeb0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70   parameters] exp
2aec0 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  anded..**.** ^(F
2aed0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2aee0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2aef0 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 75  ent is created u
2af00 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20  sing the SQL.** 
2af10 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 62  text "SELECT $ab
2af20 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70  c,:xyz" and if p
2af30 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 73  arameter $abc is
2af40 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65   bound to intege
2af50 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61  r 2345.** and pa
2af60 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20  rameter :xyz is 
2af70 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71  unbound, then sq
2af80 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c  lite3_sql() will
2af90 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f   return.** the o
2afa0 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20  riginal string, 
2afb0 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2afc0 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65  z" but sqlite3_e
2afd0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a  xpanded_sql().**
2afe0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45   will return "SE
2aff0 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e  LECT 2345,NULL".
2b000 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2b010 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2b020 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ql() interface r
2b030 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
2b040 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
2b050 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62  ry.** is availab
2b060 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  le to hold the r
2b070 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65  esult, or if the
2b080 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78   result would ex
2b090 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20  ceed the.** the 
2b0a0 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c  maximum string l
2b0b0 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64  ength determined
2b0c0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
2b0d0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  LIMIT_LENGTH]..*
2b0e0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
2b0f0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
2b100 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
2b110 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74   option limits t
2b120 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f  he size of.** bo
2b130 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65 78  und parameter ex
2b140 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20  pansions.  ^The 
2b150 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41  [SQLITE_OMIT_TRA
2b160 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
2b170 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65  .** option cause
2b180 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  s sqlite3_expand
2b190 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61  ed_sql() to alwa
2b1a0 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  ys return NULL..
2b1b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  **.** ^The strin
2b1c0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2b1d0 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20  lite3_sql(P) is 
2b1e0 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74  managed by SQLit
2b1f0 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f  e and is.** auto
2b200 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
2b210 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  when the prepare
2b220 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66  d statement is f
2b230 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68  inalized..** ^Th
2b240 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2b250 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70  d by sqlite3_exp
2b260 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e  anded_sql(P), on
2b270 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
2b280 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20  .** is obtained 
2b290 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2b2a0 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74  lloc()] and must
2b2b0 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20   be free by the 
2b2c0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62  application.** b
2b2d0 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  y passing it to 
2b2e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2b2f0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2b300 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
2b310 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2b320 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
2b330 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71  _expanded_sql(sq
2b340 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b350 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b360 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2b370 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
2b380 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
2b390 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44  tabase.** METHOD
2b3a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2b3b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b3c0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2b3d0 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
2b3e0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2b3f0 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
2b400 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
2b410 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b420 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
2b430 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
2b440 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2b450 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2b460 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2b470 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
2b480 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2b490 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
2b4a0 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
2b4b0 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
2b4c0 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
2b4d0 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
2b4e0 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
2b4f0 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
2b500 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2b510 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
2b520 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
2b530 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
2b540 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
2b550 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
2b560 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
2b570 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2b580 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
2b590 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
2b5a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2b5b0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
2b5c0 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
2b5d0 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
2b5e0 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
2b5f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2b600 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
2b610 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2b620 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
2b630 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2b640 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
2b650 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
2b660 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
2b670 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
2b680 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
2b690 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
2b6a0 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
2b6b0 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
2b6c0 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
2b6d0 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
2b6e0 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
2b6f0 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
2b700 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2b710 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
2b720 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
2b730 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
2b740 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
2b750 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
2b760 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
2b770 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
2b780 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
2b790 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
2b7a0 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
2b7b0 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
2b7c0 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
2b7d0 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
2b7e0 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
2b7f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2b800 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2b810 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
2b820 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
2b830 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
2b840 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
2b850 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
2b860 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
2b870 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
2b880 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
2b890 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2b8a0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
2b8b0 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74   on disk..*/.int
2b8c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2b8d0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
2b8e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2b8f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2b900 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
2b910 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2b920 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
2b930 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2b940 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2b950 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
2b960 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
2b970 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2b980 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
2b990 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2b9a0 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
2b9b0 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
2b9c0 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
2b9d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2b9e0 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69  (S)] but has nei
2b9f0 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70  ther run to comp
2ba00 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64  letion (returned
2ba10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2ba20 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  ] from [sqlite3_
2ba30 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a  step(S)]) nor.**
2ba40 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
2ba50 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2ba60 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
2ba70 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2ba80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2ba90 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
2baa0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2bab0 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
2bac0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
2bad0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
2bae0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
2baf0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
2bb00 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2bb10 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
2bb20 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2bb30 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2bb40 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
2bb50 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2bb60 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
2bb70 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
2bb80 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2bb90 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
2bba0 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
2bbb0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
2bbc0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
2bbd0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
2bbe0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
2bbf0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
2bc00 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
2bc10 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
2bc20 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
2bc30 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
2bc40 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
2bc50 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
2bc60 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
2bc70 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
2bc80 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
2bc90 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2bca0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2bcb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bcc0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
2bcd0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
2bce0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
2bcf0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bd00 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
2bd10 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2bd20 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
2bd30 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
2bd40 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
2bd50 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
2bd60 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
2bd70 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
2bd80 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
2bd90 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
2bda0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
2bdb0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
2bdc0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
2bdd0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
2bde0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2bdf0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
2be00 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
2be10 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
2be20 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
2be30 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
2be40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2be50 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
2be60 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
2be70 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
2be80 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
2be90 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
2bea0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2beb0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
2bec0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
2bed0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
2bee0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
2bef0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2bf00 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
2bf10 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
2bf20 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
2bf30 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
2bf40 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
2bf50 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2bf60 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
2bf70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2bf80 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  value.  The.** [
2bf90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
2bfa0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  p()] interface c
2bfb0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f  an be used to co
2bfc0 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a  nstruct a new .*
2bfd0 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  * protected sqli
2bfe0 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61  te3_value from a
2bff0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2c000 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
2c010 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
2c020 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
2c030 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
2c040 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
2c050 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
2c060 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
2c070 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
2c080 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
2c090 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2c0a0 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
2c0b0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
2c0c0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2c0d0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2c0e0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
2c0f0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2c100 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
2c110 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
2c120 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2c130 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
2c140 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
2c150 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
2c160 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
2c170 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
2c180 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
2c190 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
2c1a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2c1b0 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
2c1c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2c1d0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
2c1e0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
2c1f0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2c200 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2c210 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2c220 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c230 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
2c240 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
2c250 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
2c260 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
2c270 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
2c280 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
2c290 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
2c2a0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
2c2b0 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
2c2c0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
2c2d0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
2c2e0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2c2f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2c300 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
2c310 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
2c320 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c330 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c340 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
2c350 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
2c360 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
2c370 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
2c380 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c390 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2c3a0 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
2c3b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2c3c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
2c3d0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2c3e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2c3f0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
2c400 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
2c410 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c420 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
2c430 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2c440 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
2c450 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
2c460 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2c470 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
2c480 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c490 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
2c4a0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
2c4b0 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
2c4c0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
2c4d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c4e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
2c4f0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2c500 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
2c510 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
2c520 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
2c530 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
2c540 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
2c550 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
2c560 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
2c570 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
2c580 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
2c590 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
2c5a0 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
2c5b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2c5c0 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
2c5d0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
2c5e0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
2c5f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2c600 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2c610 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
2c620 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2c630 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2c640 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
2c650 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
2c660 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
2c670 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2c680 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
2c690 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
2c6a0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2c6b0 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
2c6c0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2c6d0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
2c6e0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2c6f0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
2c700 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
2c710 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
2c720 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2c730 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
2c740 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
2c750 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
2c760 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
2c770 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
2c780 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
2c790 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
2c7a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
2c7b0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
2c7c0 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
2c7d0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
2c7e0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
2c7f0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
2c800 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
2c810 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
2c820 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ding}.** METHOD:
2c830 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2c840 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
2c850 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2c860 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
2c870 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2c880 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
2c890 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
2c8a0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
2c8b0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
2c8c0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
2c8d0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
2c8e0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
2c8f0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
2c900 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
2c910 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
2c920 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
2c930 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
2c940 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
2c950 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
2c960 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
2c970 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
2c980 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
2c990 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
2c9a0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
2c9b0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
2c9c0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
2c9d0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
2c9e0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
2c9f0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
2ca00 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
2ca10 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
2ca20 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
2ca30 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2ca40 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
2ca50 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
2ca60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2ca70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2ca80 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
2ca90 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
2caa0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
2cab0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2cac0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
2cad0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2cae0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
2caf0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
2cb00 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
2cb10 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2cb20 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
2cb30 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
2cb40 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
2cb50 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
2cb60 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2cb70 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
2cb80 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
2cb90 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
2cba0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
2cbb0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
2cbc0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
2cbd0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
2cbe0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
2cbf0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
2cc00 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
2cc10 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
2cc20 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
2cc30 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
2cc40 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2cc50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2cc60 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
2cc70 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
2cc80 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
2cc90 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
2cca0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
2ccb0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
2ccc0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
2ccd0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
2cce0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
2ccf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
2cd00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2cd10 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
2cd20 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
2cd30 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
2cd40 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
2cd50 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
2cd60 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
2cd70 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
2cd80 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2cd90 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2cda0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2cdb0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2cdc0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2cdd0 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
2cde0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
2cdf0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2ce00 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
2ce10 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
2ce20 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
2ce30 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
2ce40 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
2ce50 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
2ce60 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
2ce70 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2ce80 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
2ce90 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2cea0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
2ceb0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
2cec0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
2ced0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2cee0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
2cef0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
2cf00 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2cf10 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
2cf20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
2cf30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2cf40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2cf50 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2cf60 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
2cf70 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
2cf80 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2cf90 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
2cfa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2cfb0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
2cfc0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2cfd0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
2cfe0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2cff0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2d000 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
2d010 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
2d020 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2d030 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
2d040 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
2d050 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
2d060 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
2d070 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
2d080 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2d090 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c  _text16() or sql
2d0a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2d0b0 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20  () then.** that 
2d0c0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2d0d0 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
2d0e0 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
2d0f0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
2d100 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
2d110 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
2d120 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
2d130 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
2d140 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
2d150 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
2d160 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
2d170 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2d180 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2d190 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
2d1a0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
2d1b0 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
2d1c0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
2d1d0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
2d1e0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
2d1f0 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
2d200 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
2d210 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
2d220 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
2d230 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
2d240 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72  the BLOB and str
2d250 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65  ing binding inte
2d260 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64  rfaces.** is a d
2d270 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
2d280 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2d290 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
2d2a0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
2d2b0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2d2c0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
2d2d0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
2d2e0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
2d2f0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
2d300 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
2d310 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50   call to bind AP
2d320 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20  I fails..** ^If 
2d330 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2d340 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
2d350 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
2d360 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
2d370 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
2d380 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
2d390 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
2d3a0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
2d3b0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
2d3c0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
2d3d0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
2d3e0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
2d3f0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
2d400 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
2d410 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
2d420 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
2d430 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2d440 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
2d450 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
2d460 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2d470 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2d480 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2d490 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
2d4a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d4b0 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
2d4c0 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
2d4d0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
2d4e0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
2d4f0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
2d500 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
2d510 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
2d520 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
2d530 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
2d540 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
2d550 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
2d560 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2d570 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2d580 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
2d590 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
2d5a0 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
2d5b0 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
2d5c0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2d5d0 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
2d5e0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
2d5f0 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
2d600 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
2d610 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
2d620 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
2d630 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d640 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2d650 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
2d660 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
2d670 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
2d680 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
2d690 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
2d6a0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
2d6b0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
2d6c0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
2d6d0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
2d6e0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
2d6f0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
2d700 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
2d710 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
2d720 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
2d730 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
2d740 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
2d750 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
2d760 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2d770 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
2d780 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
2d790 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
2d7a0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
2d7b0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
2d7c0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
2d7d0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2d7e0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
2d7f0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
2d800 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2d810 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
2d820 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2d830 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
2d840 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d850 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
2d860 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
2d870 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
2d880 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2d890 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
2d8a0 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
2d8b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d8c0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
2d8d0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
2d8e0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2d8f0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
2d900 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
2d910 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
2d920 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d930 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
2d940 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
2d950 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
2d960 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2d970 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
2d980 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
2d990 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
2d9a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
2d9b0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
2d9c0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
2d9d0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
2d9e0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
2d9f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2da00 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
2da10 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2da20 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
2da30 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
2da40 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
2da50 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
2da60 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49  * ^[SQLITE_TOOBI
2da70 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  G] might be retu
2da80 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65  rned if the size
2da90 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20   of a string or 
2daa0 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20  BLOB.** exceeds 
2dab0 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62  limits imposed b
2dac0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
2dad0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
2dae0 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b  LENGTH]) or.** [
2daf0 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
2db00 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  H]..** ^[SQLITE_
2db10 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
2db20 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
2db30 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
2db40 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
2db50 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
2db60 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
2db70 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
2db80 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2db90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2dba0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
2dbb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2dbc0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2dbd0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
2dbe0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2dbf0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
2dc00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2dc10 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2dc20 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2dc30 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
2dc40 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2dc50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2dc60 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
2dc70 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2dc80 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
2dc90 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2dca0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2dcb0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2dcc0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
2dcd0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2dce0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
2dcf0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2dd00 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
2dd10 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
2dd20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2dd30 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
2dd40 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
2dd50 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
2dd60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2dd70 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
2dd80 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
2dd90 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
2dda0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c  lite3_stmt*,int,
2ddb0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c  const char*,int,
2ddc0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2ddd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2dde0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
2ddf0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2de00 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2de10 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2de20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2de30 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
2de40 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2de50 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
2de60 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2de70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2de80 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2de90 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  , unsigned char 
2dea0 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73  encoding);.int s
2deb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2dec0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ded0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
2dee0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2def0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2df00 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
2df10 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
2df20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2df30 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73  ind_zeroblob64(s
2df40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2df50 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  t, sqlite3_uint6
2df60 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
2df70 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
2df80 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
2df90 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2dfa0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
2dfb0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
2dfc0 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
2dfd0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
2dfe0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
2dff0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
2e000 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
2e010 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
2e020 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
2e030 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
2e040 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
2e050 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
2e060 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
2e070 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
2e080 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
2e090 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e0a0 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
2e0b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
2e0c0 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
2e0d0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
2e0e0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
2e0f0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
2e100 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
2e110 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
2e120 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
2e130 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
2e140 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
2e150 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
2e160 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
2e170 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
2e180 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
2e190 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
2e1a0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
2e1b0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
2e1c0 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
2e1d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2e1e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e1f0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2e200 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2e210 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2e220 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2e230 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e240 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2e250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
2e260 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2e270 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2e280 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e290 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
2e2a0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
2e2b0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2e2c0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2e2d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e2e0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
2e2f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2e300 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
2e310 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
2e320 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2e330 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2e340 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
2e350 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
2e360 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
2e370 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2e380 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2e390 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
2e3a0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
2e3b0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
2e3c0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2e3d0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
2e3e0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
2e3f0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
2e400 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
2e410 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
2e420 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
2e430 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
2e440 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
2e450 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2e460 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
2e470 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
2e480 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
2e490 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
2e4a0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
2e4b0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
2e4c0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
2e4d0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
2e4e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
2e4f0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
2e500 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
2e510 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
2e520 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
2e530 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
2e540 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
2e550 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
2e560 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
2e570 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2e580 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
2e590 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
2e5a0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
2e5b0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
2e5c0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
2e5d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
2e5e0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
2e5f0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
2e600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2e610 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2e620 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2e630 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e640 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2e650 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2e660 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2e670 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2e680 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e690 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2e6a0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2e6b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e6c0 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
2e6d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2e6e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e6f0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
2e700 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
2e710 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f  en Name.** METHO
2e720 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2e730 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2e740 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
2e750 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
2e760 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
2e770 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
2e780 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
2e790 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
2e7a0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
2e7b0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
2e7c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2e7d0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
2e7e0 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
2e7f0 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
2e800 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
2e810 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
2e820 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
2e830 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
2e840 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
2e850 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
2e860 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
2e870 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
2e880 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
2e890 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e8a0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2e8b0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2e8c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2e8d0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2e8e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e8f0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2e900 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2e910 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e920 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  r_name()]..*/.in
2e930 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2e940 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
2e950 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
2e960 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
2e970 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e980 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
2e990 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
2e9a0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2e9b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2e9c0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  _stmt.**.** ^Con
2e9d0 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
2e9e0 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
2e9f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ea00 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
2ea10 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2ea20 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
2ea30 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
2ea40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ea50 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
2ea60 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
2ea70 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
2ea80 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
2ea90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
2eaa0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2eab0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2eac0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2ead0 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
2eae0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2eaf0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2eb00 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
2eb10 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2eb20 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2eb30 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2eb40 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2eb50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2eb60 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2eb70 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2eb80 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2eb90 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2eba0 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2ebb0 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2ebc0 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2ebd0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2ebe0 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2ebf0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2ec00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2ec10 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2ec20 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2ec30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2ec40 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2ec50 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2ec60 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ec70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2ec80 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2ec90 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
2eca0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
2ecb0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
2ecc0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2ecd0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2ece0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
2ecf0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2ed00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2ed10 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2ed20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2ed30 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
2ed40 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
2ed50 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2ed60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2ed70 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2ed80 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
2ed90 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2eda0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2edb0 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
2edc0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
2edd0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2ede0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2edf0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
2ee00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2ee10 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
2ee20 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
2ee30 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
2ee40 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
2ee50 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2ee60 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
2ee70 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
2ee80 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2ee90 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
2eea0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
2eeb0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2eec0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2eed0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2eee0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2eef0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2ef00 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2ef10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2ef20 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2ef30 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2ef40 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2ef50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2ef60 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
2ef70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2ef80 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
2ef90 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2efa0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
2efb0 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
2efc0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
2efd0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
2efe0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
2eff0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
2f000 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
2f010 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
2f020 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
2f030 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2f040 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2f050 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
2f060 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
2f070 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
2f080 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
2f090 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
2f0a0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
2f0b0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
2f0c0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
2f0d0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
2f0e0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
2f0f0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
2f100 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
2f110 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
2f120 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
2f130 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
2f140 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f150 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2f160 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
2f170 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f180 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
2f190 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2f1a0 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
2f1b0 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
2f1c0 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
2f1d0 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
2f1e0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2f1f0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2f200 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2f210 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2f220 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2f230 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2f240 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2f250 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2f260 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2f270 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2f280 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2f290 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2f2a0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2f2b0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2f2c0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2f2d0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2f2e0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2f2f0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2f300 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2f310 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2f320 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2f330 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2f340 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2f350 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2f360 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2f370 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2f380 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2f390 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2f3a0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2f3b0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2f3c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f3d0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2f3e0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2f3f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2f400 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2f410 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2f420 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2f430 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2f440 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2f450 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2f460 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2f470 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2f480 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2f490 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2f4a0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2f4b0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2f4c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2f4d0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2f4e0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2f4f0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2f500 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2f510 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2f520 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2f530 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2f540 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2f550 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2f560 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2f570 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2f580 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2f590 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2f5a0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2f5b0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2f5c0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2f5d0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2f5e0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2f5f0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2f600 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2f610 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2f620 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2f630 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2f640 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2f650 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2f660 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2f670 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2f680 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2f690 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2f6a0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2f6b0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2f6c0 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2f6d0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2f6e0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2f6f0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2f700 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2f710 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2f720 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2f730 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2f740 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2f750 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2f760 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2f770 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2f780 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2f790 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2f7a0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2f7b0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2f7c0 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2f7d0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2f7e0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2f7f0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2f800 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2f810 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2f820 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2f830 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2f840 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2f850 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2f860 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2f870 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2f880 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2f890 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2f8a0 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2f8b0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2f8c0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2f8d0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2f8e0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2f8f0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2f900 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
2f910 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
2f920 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2f930 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
2f940 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2f950 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2f960 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2f970 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
2f980 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2f990 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
2f9a0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
2f9b0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
2f9c0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
2f9d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2f9e0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
2f9f0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
2fa00 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2fa10 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2fa20 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
2fa30 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2fa40 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2fa50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2fa60 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2fa70 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2fa80 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2fa90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2faa0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2fab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fac0 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2fad0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2fae0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2faf0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2fb00 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2fb10 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2fb20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2fb30 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2fb40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2fb50 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2fb60 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2fb70 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2fb80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2fb90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fba0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2fbb0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2fbc0 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
2fbd0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2fbe0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
2fbf0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2fc00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fc10 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
2fc20 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2fc30 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2fc40 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
2fc50 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
2fc60 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
2fc70 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
2fc80 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
2fc90 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
2fca0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2fcb0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
2fcc0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2fcd0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
2fce0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
2fcf0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
2fd00 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2fd10 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
2fd20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2fd30 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
2fd40 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2fd50 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2fd60 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2fd70 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
2fd80 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
2fd90 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2fda0 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
2fdb0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
2fdc0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
2fdd0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
2fde0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
2fdf0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
2fe00 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2fe10 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
2fe20 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
2fe30 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
2fe40 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
2fe50 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
2fe60 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
2fe70 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
2fe80 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
2fe90 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
2fea0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
2feb0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
2fec0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
2fed0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
2fee0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
2fef0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
2ff00 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
2ff10 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
2ff20 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
2ff30 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
2ff40 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
2ff50 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
2ff60 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
2ff70 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
2ff80 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
2ff90 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
2ffa0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
2ffb0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
2ffc0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
2ffd0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
2ffe0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
2fff0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
30000 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
30010 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
30020 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
30030 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
30040 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
30050 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
30060 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
30070 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
30080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
30090 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
300a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
300b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
300c0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
300d0 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
300e0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
300f0 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
30100 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30110 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
30120 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
30130 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
30140 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
30150 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30160 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
30170 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
30180 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
30190 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
301a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
301b0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
301c0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
301d0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
301e0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
301f0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
30200 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
30210 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
30220 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
30230 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
30240 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
30250 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
30260 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
30270 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
30280 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
30290 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
302a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
302b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
302c0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
302d0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
302e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
302f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
30300 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
30310 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
30320 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
30330 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
30340 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
30350 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
30360 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
30370 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
30380 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
30390 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
303a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
303b0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
303c0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
303d0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
303e0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
303f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
30400 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
30410 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
30420 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
30430 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
30440 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
30450 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
30460 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
30470 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
30480 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
30490 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
304a0 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
304b0 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
304c0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
304d0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
304e0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
304f0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
30500 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
30510 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
30520 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
30530 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
30540 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
30550 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
30560 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
30570 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
30580 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
30590 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
305a0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
305b0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
305c0 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
305d0 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
305e0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
305f0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
30600 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
30610 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
30620 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
30630 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
30640 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
30650 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
30660 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
30670 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
30680 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
30690 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
306a0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
306b0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
306c0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
306d0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
306e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
306f0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
30700 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
30710 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
30720 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
30730 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
30740 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
30750 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
30760 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
30770 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
30780 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
30790 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
307a0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
307b0 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
307c0 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
307d0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
307e0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
307f0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
30800 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
30810 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
30820 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
30830 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
30840 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
30850 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
30860 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
30870 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
30880 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
30890 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
308a0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
308b0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
308c0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
308d0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
308e0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
308f0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
30900 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
30910 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
30920 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
30930 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
30940 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
30950 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
30960 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
30970 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
30980 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
30990 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
309a0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
309b0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
309c0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
309d0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
309e0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
309f0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
30a00 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
30a10 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
30a20 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
30a30 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
30a40 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
30a50 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
30a60 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
30a70 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
30a80 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
30a90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
30aa0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
30ab0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
30ac0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
30ad0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
30ae0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
30af0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
30b00 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
30b10 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
30b20 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
30b30 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
30b40 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
30b50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
30b60 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
30b70 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
30b80 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
30b90 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
30ba0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
30bb0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
30bc0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
30bd0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
30be0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
30bf0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
30c00 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
30c10 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
30c20 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
30c30 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
30c40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
30c50 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
30c60 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
30c70 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
30c80 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
30c90 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
30ca0 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
30cb0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
30cc0 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
30cd0 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
30ce0 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
30cf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
30d00 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
30d10 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
30d20 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
30d30 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
30d40 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
30d50 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
30d60 74 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e  t after [version
30d70 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74   3.6.23.1] ([dat
30d80 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a  eof:3.6.23.1],.*
30d90 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
30da0 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
30db0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
30dc0 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
30dd0 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
30de0 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
30df0 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
30e00 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
30e10 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
30e20 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
30e30 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
30e40 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
30e50 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
30e60 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
30e70 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
30e80 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
30e90 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
30ea0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
30eb0 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
30ec0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
30ed0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
30ee0 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
30ef0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
30f00 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
30f10 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
30f20 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
30f30 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
30f40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
30f50 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
30f60 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
30f70 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
30f80 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
30f90 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
30fa0 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
30fb0 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
30fc0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
30fd0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
30fe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
30ff0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
31000 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
31010 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
31020 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
31030 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
31040 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
31050 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
31060 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
31070 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
31080 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
31090 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
310a0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
310b0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
310c0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
310d0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
310e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
310f0 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
31100 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31110 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
31120 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
31130 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
31140 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
31150 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
31160 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
31170 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
31180 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
31190 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
311a0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
311b0 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
311c0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
311d0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
311e0 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
311f0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
31200 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
31210 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
31220 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
31230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
31240 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
31250 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
31260 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
31270 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
31280 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
31290 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
312a0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
312b0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
312c0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
312d0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
312e0 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
312f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31300 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
31310 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
31320 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
31330 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
31340 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
31350 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
31360 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
31370 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31380 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
31390 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
313a0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
313b0 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
313c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
313d0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
313e0 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
313f0 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
31400 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
31410 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
31420 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
31430 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
31440 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
31450 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
31460 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
31470 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
31480 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
31490 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
314a0 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
314b0 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
314c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
314d0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
314e0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
314f0 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
31500 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
31510 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
31520 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
31530 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
31540 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
31550 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
31560 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
31570 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
31580 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
31590 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
315a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
315b0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
315c0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
315d0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
315e0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
315f0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
31600 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
31610 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
31620 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
31630 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
31640 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
31650 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
31660 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
31670 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
31680 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
31690 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
316a0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
316b0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
316c0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
316d0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
316e0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
316f0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
31700 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
31710 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
31720 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
31730 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
31740 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
31750 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
31760 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
31770 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
31780 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
31790 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
317a0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
317b0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
317c0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
317d0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
317e0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
317f0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
31800 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
31810 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
31820 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
31830 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
31840 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
31850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
31860 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
31870 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
31880 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
31890 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
318a0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
318b0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
318c0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
318d0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
318e0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
318f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
31900 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
31910 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
31920 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
31930 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
31940 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31950 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31960 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
31970 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
31980 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
31990 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
319a0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
319b0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
319c0 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
319d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
319e0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
319f0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
31a00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31a10 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
31a20 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
31a30 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
31a40 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
31a50 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
31a60 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
31a70 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
31a80 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
31a90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
31aa0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
31ab0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
31ac0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
31ad0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
31ae0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
31af0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
31b00 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
31b10 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
31b20 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
31b30 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
31b40 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
31b50 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
31b60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
31b70 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
31b80 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
31b90 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
31ba0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
31bb0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
31bc0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
31bd0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
31be0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
31bf0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
31c00 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
31c10 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
31c20 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
31c30 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
31c40 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
31c50 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
31c60 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
31c70 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
31c80 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
31c90 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
31ca0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
31cb0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
31cc0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
31cd0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
31ce0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
31cf0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
31d00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
31d10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
31d20 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
31d30 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
31d40 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
31d50 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
31d60 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
31d70 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
31d80 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
31d90 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
31da0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
31db0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
31dc0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31dd0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
31de0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
31df0 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
31e00 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
31e10 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
31e20 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
31e30 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
31e40 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
31e50 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
31e60 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
31e70 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
31e80 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
31e90 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
31ea0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
31eb0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
31ec0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
31ed0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
31ee0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
31ef0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
31f00 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
31f10 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
31f20 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
31f30 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
31f40 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
31f50 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
31f60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31f70 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
31f80 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
31f90 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
31fa0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
31fb0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
31fc0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
31fd0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
31fe0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
31ff0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
32000 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
32010 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
32020 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
32030 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
32040 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
32050 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
32060 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
32070 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
32080 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
32090 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
320a0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
320b0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
320c0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
320d0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
320e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
320f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
32100 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
32110 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
32120 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
32130 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
32140 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
32150 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
32160 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
32170 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
32180 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
32190 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
321a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
321b0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
321c0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
321d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
321e0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
321f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
32200 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
32210 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
32220 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
32230 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
32240 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
32250 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
32260 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
32270 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
32280 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32290 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
322a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
322b0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
322c0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
322d0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
322e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
322f0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
32300 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
32310 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
32320 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
32330 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
32340 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
32350 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
32360 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32370 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
32380 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
32390 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
323a0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
323b0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
323c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
323d0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
323e0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
323f0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
32400 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
32410 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
32420 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
32430 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
32440 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
32450 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
32460 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
32470 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
32480 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
32490 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
324a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
324b0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
324c0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
324d0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
324e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
324f0 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
32500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32510 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
32520 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
32530 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
32540 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
32550 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
32560 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
32570 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
32580 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
32590 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
325a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
325b0 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
325c0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
325d0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
325e0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
325f0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
32600 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
32610 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
32620 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32630 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
32640 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
32650 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
32660 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
32670 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
32680 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
32690 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
326a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
326b0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
326c0 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
326d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
326e0 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c  .** <b>Warning:<
326f0 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  /b> ^The object 
32700 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
32710 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
32720 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
32730 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
32740 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32750 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72  .  In a multithr
32760 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e  eaded environmen
32770 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65  t,.** an unprote
32780 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32790 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e  ue object may on
327a0 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c  ly be used safel
327b0 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  y with.** [sqlit
327c0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
327d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
327e0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
327f0 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
32800 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32810 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
32820 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
32830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
32840 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
32850 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
32860 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
32870 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
32880 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
32890 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
328a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
328b0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
328c0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
328d0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
328e0 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a  not threadsafe..
328f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
32900 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
32910 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
32920 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
32930 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
32940 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
32950 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
32960 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
32970 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
32980 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
32990 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
329a0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
329b0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
329c0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
329d0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
329e0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
329f0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
32a00 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
32a10 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
32a20 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
32a30 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
32a40 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
32a50 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
32a60 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
32a70 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
32a80 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
32a90 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
32aa0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
32ab0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
32ac0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
32ad0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
32ae0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
32af0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
32b00 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
32b10 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
32b20 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
32b30 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
32b40 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
32b50 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
32b60 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
32b70 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
32b80 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
32b90 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
32ba0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
32bb0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
32bc0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
32bd0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
32be0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
32bf0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
32c00 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
32c10 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
32c20 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
32c30 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
32c40 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
32c50 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
32c60 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
32c70 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
32c80 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
32c90 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
32ca0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
32cb0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
32cc0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
32cd0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
32ce0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
32cf0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
32d00 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
32d10 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
32d20 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
32d30 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
32d40 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
32d50 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
32d60 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
32d70 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
32d80 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
32d90 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
32da0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
32db0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
32dc0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
32dd0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
32de0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
32df0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
32e00 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
32e10 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
32e20 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
32e30 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
32e40 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
32e50 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
32e60 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
32e70 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
32e80 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
32e90 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
32ea0 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
32eb0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
32ec0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
32ed0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
32ee0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
32ef0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
32f00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32f10 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
32f20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32f30 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
32f40 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
32f50 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
32f60 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
32f70 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
32f80 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
32f90 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
32fa0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
32fb0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
32fc0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
32fd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
32fe0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
32ff0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
33000 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
33010 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
33020 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
33030 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
33040 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
33050 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
33060 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
33070 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
33080 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
33090 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
330a0 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
330b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
330c0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
330d0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
330e0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
330f0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
33100 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
33110 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
33120 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
33130 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
33140 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
33150 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
33160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
33170 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
33180 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
33190 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
331a0 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
331b0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
331c0 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
331d0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
331e0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
331f0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
33200 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
33210 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
33220 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
33230 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
33240 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
33250 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
33260 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
33270 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
33280 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
33290 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
332a0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
332b0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
332c0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
332d0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
332e0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
332f0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
33300 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
33310 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
33320 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
33330 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
33340 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20  e safest policy 
33350 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
33360 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
33370 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
33380 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
33390 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
333a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
333b0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
333c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
333d0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
333e0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
333f0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
33400 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
33410 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
33420 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
33430 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33440 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
33450 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33460 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
33470 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
33480 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
33490 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
334a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
334b0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
334c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
334d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
334e0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
334f0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
33500 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
33510 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
33520 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
33530 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
33540 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
33550 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
33560 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
33570 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
33580 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
33590 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
335a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
335b0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
335c0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
335d0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
335e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
335f0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
33600 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
33610 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
33620 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
33630 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
33640 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
33650 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
33660 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
33670 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
33680 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
33690 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
336a0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
336b0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
336c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
336d0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
336e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
336f0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
33700 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
33710 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
33720 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
33730 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
33740 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
33750 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73  em>not</em> pass
33760 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
33770 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
33780 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33790 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
337a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
337b0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
337c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
337d0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
337e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
337f0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
33800 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
33810 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
33820 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
33830 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
33840 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
33850 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
33860 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
33870 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
33880 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
33890 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
338a0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
338b0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
338c0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
338d0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
338e0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
338f0 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
33900 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33910 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
33920 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33930 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
33940 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
33950 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
33960 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
33970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33980 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
33990 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
339a0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
339b0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
339c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
339d0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
339e0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
339f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33a00 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
33a10 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
33a20 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
33a30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
33a40 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
33a50 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
33a60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
33a70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33a80 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
33a90 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
33aa0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
33ab0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
33ac0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
33ad0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
33ae0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
33af0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
33b00 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
33b10 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
33b20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
33b30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33b40 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
33b50 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
33b60 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52   Object.** DESTR
33b70 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
33b80 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
33b90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33ba0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
33bb0 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
33bc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33bd0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
33be0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
33bf0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
33c00 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
33c10 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
33c20 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
33c30 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
33c40 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
33c50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
33c60 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
33c70 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
33c80 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
33c90 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
33ca0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
33cb0 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
33cc0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
33cd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
33ce0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
33cf0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
33d00 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
33d10 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
33d20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
33d30 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
33d40 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
33d50 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
33d60 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
33d70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33d80 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
33d90 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
33da0 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
33db0 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
33dc0 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
33dd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
33de0 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
33df0 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
33e00 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
33e10 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
33e20 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
33e30 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
33e40 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
33e50 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
33e60 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
33e70 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
33e80 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
33e90 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
33ea0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
33eb0 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
33ec0 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
33ed0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
33ee0 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
33ef0 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
33f00 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
33f10 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
33f20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
33f30 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
33f40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33f50 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
33f60 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
33f70 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
33f80 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
33f90 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
33fa0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
33fb0 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
33fc0 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
33fd0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
33fe0 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
33ff0 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
34000 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
34010 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
34020 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
34030 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
34040 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
34050 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
34060 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d  ment Object.** M
34070 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
34080 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  tmt.**.** The sq
34090 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
340a0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
340b0 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
340c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
340d0 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
340e0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
340f0 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
34100 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
34110 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
34120 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
34130 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
34140 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
34150 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
34160 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
34170 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
34180 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
34190 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
341a0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
341b0 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
341c0 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
341d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
341e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
341f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
34200 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
34210 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
34220 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
34230 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
34240 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
34250 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
34260 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
34270 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
34280 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
34290 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
342a0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
342b0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
342c0 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
342d0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
342e0 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
342f0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
34300 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
34310 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
34320 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
34330 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
34340 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
34350 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
34360 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
34370 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34380 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
34390 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
343a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
343b0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
343c0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
343d0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
343e0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
343f0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
34400 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
34410 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
34420 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
34430 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
34440 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
34450 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34460 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
34470 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
34480 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
34490 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
344a0 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
344b0 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
344c0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
344d0 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
344e0 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
344f0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
34500 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
34510 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
34520 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
34530 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
34540 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  L functions}.** 
34550 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
34560 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
34570 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
34580 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
34590 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
345a0 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
345b0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
345c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
345d0 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
345e0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
345f0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
34600 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
34610 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
34620 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
34630 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
34640 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
34650 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
34660 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
34670 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
34680 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
34690 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
346a0 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
346b0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
346c0 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
346d0 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
346e0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
346f0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
34700 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
34710 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
34720 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
34730 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
34740 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
34750 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
34760 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
34770 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
34780 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
34790 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
347a0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
347b0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
347c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
347d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
347e0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
347f0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
34800 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
34810 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
34820 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
34830 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
34840 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
34850 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
34860 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
34870 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
34880 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
34890 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
348a0 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
348b0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
348c0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
348d0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
348e0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
348f0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
34900 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
34910 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
34920 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
34930 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
34940 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
34950 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
34960 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
34970 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
34980 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
34990 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
349a0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
349b0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
349c0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
349d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
349e0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
349f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
34a00 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
34a10 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
34a20 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
34a30 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
34a40 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
34a50 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
34a60 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
34a70 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
34a80 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
34a90 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
34aa0 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
34ab0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
34ac0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
34ad0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
34ae0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
34af0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
34b00 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
34b10 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
34b20 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
34b30 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
34b40 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
34b50 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
34b60 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
34b70 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
34b80 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
34b90 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
34ba0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
34bb0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
34bc0 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73   should set this
34bd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
34be0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
34bf0 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f  ] if the functio
34c00 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
34c10 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71   invokes .** [sq
34c20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34c30 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16le()] on an in
34c40 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  put, or [SQLITE_
34c50 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a  UTF16BE] if the.
34c60 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
34c70 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74  n invokes [sqlit
34c80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
34c90 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
34ca0 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
34cb0 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74  UTF16] if [sqlit
34cc0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
34cd0 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b  )] is used, or [
34ce0 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20  SQLITE_UTF8].** 
34cf0 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65  otherwise.  ^The
34d00 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
34d10 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
34d20 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
34d30 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66  mes using.** dif
34d40 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64  ferent preferred
34d50 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c   text encodings,
34d60 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
34d70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
34d80 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f  for.** each enco
34d90 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  ding..** ^When m
34da0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
34db0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
34dc0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
34dd0 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
34de0 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
34df0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
34e00 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
34e10 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
34e20 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
34e30 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
34e40 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f  ameter may optio
34e50 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69  nally be ORed wi
34e60 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  th [SQLITE_DETER
34e70 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20  MINISTIC].** to 
34e80 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20  signal that the 
34e90 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c  function will al
34ea0 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
34eb0 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65  same result give
34ec0 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e  n.** the same in
34ed0 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69  puts within a si
34ee0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
34ef0 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75  nt.  Most SQL fu
34f00 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64  nctions are.** d
34f10 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
34f20 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e  he built-in [ran
34f30 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74  dom()] SQL funct
34f40 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  ion is an exampl
34f50 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69  e of a.** functi
34f60 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64  on that is not d
34f70 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
34f80 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20  he SQLite query 
34f90 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20  planner is able 
34fa0 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64  to.** perform ad
34fb0 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a  ditional optimiz
34fc0 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d  ations on determ
34fd0 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  inistic function
34fe0 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20  s, so use.** of 
34ff0 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  the [SQLITE_DETE
35000 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20  RMINISTIC] flag 
35010 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77  is recommended w
35020 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  here possible..*
35030 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
35040 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
35050 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
35060 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
35070 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
35080 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
35090 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
350a0 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
350b0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
350c0 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
350d0 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
350e0 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
350f0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
35100 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
35110 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
35120 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
35130 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
35140 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
35150 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
35160 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
35170 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
35180 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
35190 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
351a0 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
351b0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
351c0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
351d0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
351e0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
351f0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
35200 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
35210 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
35220 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
35230 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
35240 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
35250 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
35260 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
35270 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
35280 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
35290 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
352a0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
352b0 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
352c0 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
352d0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
352e0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
352f0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
35300 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
35310 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35320 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
35330 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
35340 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
35350 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
35360 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
35370 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
35380 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
35390 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
353a0 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
353b0 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
353c0 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
353d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
353e0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
353f0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
35400 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
35410 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
35420 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
35430 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
35440 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
35450 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
35460 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
35470 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
35480 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
35490 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
354a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
354b0 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
354c0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
354d0 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
354e0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
354f0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
35500 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
35510 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
35520 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
35530 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
35540 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
35550 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
35560 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
35570 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
35580 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
35590 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
355a0 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
355b0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
355c0 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
355d0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
355e0 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
355f0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
35600 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
35610 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
35620 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
35630 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
35640 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
35650 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
35660 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
35670 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
35680 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
35690 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
356a0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
356b0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
356c0 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
356d0 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
356e0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
356f0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
35700 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
35710 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
35720 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
35730 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
35740 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
35750 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
35760 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
35770 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
35780 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
35790 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
357a0 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
357b0 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
357c0 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
357d0 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
357e0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
357f0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
35800 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
35810 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
35820 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
35830 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
35840 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
35850 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
35860 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35870 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
35880 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
35890 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
358a0 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
358b0 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
358c0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
358d0 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
358e0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
358f0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
35900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
35910 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
35920 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
35930 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
35940 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
35950 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
35960 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35970 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
35980 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
35990 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
359a0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
359b0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
359c0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
359d0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
359e0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
359f0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
35a00 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
35a10 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
35a20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
35a30 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
35a40 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
35a50 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
35a60 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
35a70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35a80 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
35a90 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
35aa0 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
35ab0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
35ac0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
35ad0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
35ae0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
35af0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35b00 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35b10 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
35b20 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
35b30 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
35b40 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
35b50 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
35b60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35b70 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
35b80 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
35b90 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
35ba0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
35bb0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
35bc0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
35bd0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
35be0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
35bf0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
35c00 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
35c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
35c20 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
35c30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35c40 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
35c50 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
35c60 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
35c70 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
35c80 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
35c90 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
35ca0 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
35cb0 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
35cc0 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
35cd0 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
35ce0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
35cf0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
35d00 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
35d10 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
35d20 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
35d30 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
35d40 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50       1    /* IMP
35d50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20  : R-37514-35566 
35d60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
35d70 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
35d80 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   2    /* IMP: R-
35d90 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23  03371-37637 */.#
35da0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
35db0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20  F16BE        3  
35dc0 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37    /* IMP: R-5197
35dd0 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69  1-34154 */.#defi
35de0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
35df0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
35e00 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
35e10 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
35e20 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
35e30 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
35e40 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64  Deprecated */.#d
35e50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
35e60 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
35e70 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
35e80 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
35e90 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
35ea0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46  3REF: Function F
35eb0 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lags.**.** These
35ec0 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
35ed0 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20  e ORed together 
35ee0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
35ef0 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66  LITE_UTF8 | pref
35f00 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
35f10 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72  ing] as the four
35f20 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
35f30 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
35f40 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b  e_function()], [
35f50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35f60 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  unction16()], or
35f70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
35f80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
35f90 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
35fa0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
35fb0 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a  TIC    0x800../*
35fc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
35fd0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
35fe0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
35ff0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
36000 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
36010 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
36020 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
36030 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
36040 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
36050 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
36060 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
36070 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
36080 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
36090 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
360a0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
360b0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
360c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
360d0 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72   To encourage pr
360e0 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f  ogrammers to avo
360f0 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63  id.** these func
36100 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e  tions, we will n
36110 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20  ot explain what 
36120 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
36130 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
36140 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
36150 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
36160 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
36170 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
36180 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
36190 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
361a0 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
361b0 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
361c0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
361d0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
361e0 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
361f0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
36200 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
36210 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
36220 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
36230 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
36240 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
36250 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
36260 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
36270 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
36280 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
36290 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
362a0 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
362b0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
362c0 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20  ,int),.         
362d0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
362e0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
362f0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
36300 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
36310 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a  ning SQL Values.
36320 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
36330 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54  e3_value.**.** T
36340 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
36350 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
36360 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
36370 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
36380 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
36390 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
363a0 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
363b0 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
363c0 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
363d0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
363e0 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.  .**.** The 
363f0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
36400 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
36410 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
36420 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
36430 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
36440 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36450 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
36460 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36470 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
36480 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
36490 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
364a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
364b0 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
364c0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
364d0 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
364e0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
364f0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
36500 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
36510 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
36520 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
36530 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
36540 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
36550 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
36560 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
36570 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
36580 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
36590 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
365a0 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
365b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
365c0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
365d0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
365e0 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
365f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
36600 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
36610 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
36620 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
36630 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
36640 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
36650 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
36660 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
36670 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
36680 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
36690 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
366a0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
366b0 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
366c0 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
366d0 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65  xcept that these
366e0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
366f0 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
36700 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
36710 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
36720 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
36730 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
36740 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
36750 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
36760 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
36770 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
36780 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
36790 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
367a0 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
367b0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
367c0 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
367d0 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
367e0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
367f0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
36800 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
36810 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
36820 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
36830 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
36840 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
36850 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
36860 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
36870 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
36880 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
36890 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
368a0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
368b0 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
368c0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
368d0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
368e0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
368f0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
36900 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
36910 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
36920 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
36930 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
36940 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
36950 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
36960 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
36970 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
36980 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
36990 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
369a0 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
369b0 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
369c0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
369d0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
369e0 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
369f0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
36a00 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
36a10 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
36a20 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
36a30 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
36a40 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
36a50 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
36a60 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
36a70 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
36a80 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
36a90 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
36aa0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
36ab0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
36ac0 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
36ad0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36ae0 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
36af0 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
36b00 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
36b10 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
36b20 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
36b30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
36b40 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
36b50 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
36b60 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
36b70 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
36b80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
36b90 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
36ba0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
36bb0 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
36bc0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
36bd0 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
36be0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
36bf0 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
36c00 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
36c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
36c20 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
36c30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
36c40 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
36c50 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
36c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
36c70 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
36c80 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
36c90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
36ca0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
36cb0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
36cc0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
36cd0 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
36ce0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
36cf0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
36d00 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
36d10 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
36d20 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
36d30 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
36d40 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
36d50 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
36d60 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
36d70 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
36d80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
36d90 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
36da0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
36db0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
36dc0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
36dd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
36de0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
36df0 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
36e00 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
36e10 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
36e20 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
36e30 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
36e40 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 69 6e  CAPI3REF: Findin
36e50 67 20 54 68 65 20 53 75 62 74 79 70 65 20 4f 66  g The Subtype Of
36e60 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d   SQL Values.** M
36e70 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76  ETHOD: sqlite3_v
36e80 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  alue.**.** The s
36e90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62  qlite3_value_sub
36ea0 74 79 70 65 28 56 29 20 66 75 6e 63 74 69 6f 6e  type(V) function
36eb0 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 75 62   returns the sub
36ec0 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b  type for.** an [
36ed0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36ee0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
36ef0 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e 20 20 54  ] argument V.  T
36f00 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e  he subtype.** in
36f10 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65  formation can be
36f20 20 75 73 65 64 20 74 6f 20 70 61 73 73 20 61 20   used to pass a 
36f30 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f  limited amount o
36f40 66 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a  f context from.*
36f50 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74 69  * one SQL functi
36f60 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20  on to another.  
36f70 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
36f80 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28  _result_subtype(
36f90 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  )].** routine to
36fa0 20 73 65 74 20 74 68 65 20 73 75 62 74 79 70 65   set the subtype
36fb0 20 66 6f 72 20 74 68 65 20 72 65 74 75 72 6e 20   for the return 
36fc0 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20  value of an SQL 
36fd0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
36fe0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20  SQLite makes no 
36ff0 75 73 65 20 6f 66 20 73 75 62 74 79 70 65 20 69  use of subtype i
37000 74 73 65 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c  tself.  It merel
37010 79 20 70 61 73 73 65 73 20 74 68 65 20 73 75 62  y passes the sub
37020 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  type.** from the
37030 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b   result of one [
37040 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37050 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
37060 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e  ] into the.** in
37070 70 75 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a  put of another..
37080 2a 2f 0a 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  */.unsigned int 
37090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75  sqlite3_value_su
370a0 62 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  btype(sqlite3_va
370b0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
370c0 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64  PI3REF: Copy And
370d0 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73   Free SQL Values
370e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
370f0 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
37100 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
37110 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66  ue_dup(V) interf
37120 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
37130 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
37140 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
37150 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20  t D and returns 
37160 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
37170 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73  t copy.  ^The [s
37180 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65  qlite3_value] re
37190 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b  turned.** is a [
371a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
371b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
371c0 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75  even if the inpu
371d0 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68  t is not..** ^Th
371e0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
371f0 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65  dup(V) interface
37200 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
37210 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66   V is NULL or if
37220 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
37230 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a  ocation fails..*
37240 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37250 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20  3_value_free(V) 
37260 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20  interface frees 
37270 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  an [sqlite3_valu
37280 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65  e] object.** pre
37290 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
372a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
372b0 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49  alue_dup()].  ^I
372c0 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f V is a NULL po
372d0 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71  inter.** then sq
372e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
372f0 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73  (V) is a harmles
37300 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c 69  s no-op..*/.sqli
37310 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
37320 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e  e3_value_dup(con
37330 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
37340 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
37350 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69  _value_free(sqli
37360 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
37370 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
37380 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
37390 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
373a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
373b0 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
373c0 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
373d0 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
373e0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
373f0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
37400 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
37410 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
37420 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
37430 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
37440 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
37450 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37460 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
37470 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
37480 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
37490 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
374a0 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
374b0 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
374c0 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
374d0 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
374e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
374f0 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
37500 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
37510 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
37520 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
37530 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37540 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
37550 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
37560 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
37570 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
37580 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
37590 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
375a0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
375b0 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
375c0 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
375d0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
375e0 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
375f0 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
37600 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
37610 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
37620 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
37630 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
37640 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
37650 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
37660 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
37670 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
37680 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
37690 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
376a0 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
376b0 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
376c0 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
376d0 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
376e0 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
376f0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37700 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
37710 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
37720 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
37730 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
37740 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
37750 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37760 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
37770 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
37780 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77  LL pointer .** w
37790 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64  hen first called
377a0 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   if N is less th
377b0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
377c0 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
377d0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65  ry.** allocate e
377e0 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
377f0 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
37800 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
37810 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
37820 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37830 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
37840 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
37850 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
37860 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
37870 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
37880 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
37890 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
378a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
378b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
378c0 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
378d0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
378e0 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
378f0 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
37900 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
37910 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74  location.)^  Wit
37920 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hin the xFinal c
37930 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63  allback, it is c
37940 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a  ustomary to set.
37950 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20  ** N=0 in calls 
37960 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
37970 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
37980 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a  ) so that no .**
37990 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72   pointless memor
379a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63  y allocations oc
379b0 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  cur..**.** ^SQLi
379c0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
379d0 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
379e0 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
379f0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
37a00 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
37a10 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
37a20 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
37a30 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
37a40 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
37a50 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
37a60 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
37a70 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
37a80 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
37a90 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
37aa0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
37ab0 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
37ac0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
37ad0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
37ae0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
37af0 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
37b00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
37b10 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
37b20 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
37b30 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
37b40 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
37b50 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
37b60 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
37b70 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
37b80 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
37b90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37ba0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
37bb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
37bc0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
37bd0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
37be0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
37bf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37c00 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
37c10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37c20 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
37c30 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
37c40 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
37c50 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
37c60 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
37c70 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
37c80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
37c90 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
37ca0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
37cb0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
37cc0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
37cd0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
37ce0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
37cf0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
37d00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
37d10 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
37d20 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
37d30 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
37d40 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
37d50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37d60 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
37d70 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
37d80 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
37d90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
37da0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37db0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
37dc0 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
37dd0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
37de0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
37df0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37e00 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
37e10 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
37e20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
37e30 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
37e40 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
37e50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
37e60 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
37e70 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
37e80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
37e90 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
37ea0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37eb0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
37ec0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
37ed0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
37ee0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
37ef0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
37f00 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ction..*/.sqlite
37f10 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
37f20 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
37f30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
37f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37f50 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
37f60 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48  ary Data.** METH
37f70 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
37f80 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ext.**.** These 
37f90 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
37fa0 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67   used by (non-ag
37fb0 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e  gregate) SQL fun
37fc0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
37fd0 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
37fe0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
37ff0 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
38000 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
38010 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
38020 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
38030 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
38040 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
38050 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
38060 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
38070 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
38080 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
38090 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
380a0 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a  ed.  An example.
380b0 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73  ** of where this
380c0 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c   might be useful
380d0 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72   is in a regular
380e0 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
380f0 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  hing.** function
38100 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
38110 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
38120 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
38130 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61   can be stored a
38140 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
38150 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
38160 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
38170 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c  .  .** Then as l
38180 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65  ong as the patte
38190 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e  rn string remain
381a0 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74  s the same,.** t
381b0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
381c0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
381d0 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
381e0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
381f0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
38200 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ame function..**
38210 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
38220 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
38230 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
38240 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
38250 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
38260 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
38270 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
38280 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
38290 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
382a0 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
382b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
382c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
382d0 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  n. ^If there is 
382e0 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  no metadata.** a
382f0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
38300 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  he function argu
38310 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74  ment, this sqlit
38320 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
38330 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
38340 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
38350 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
38360 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
38370 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e  data(C,N,P,X) in
38380 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20  terface saves P 
38390 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  as metadata for 
383a0 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
383b0 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
383c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
383d0 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73  function.  ^Subs
383e0 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
383f0 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
38400 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75  uxdata(C,N) retu
38410 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f  rn P from the mo
38420 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c  st recent.** sql
38430 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
38440 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69  (C,N,P,X) call i
38450 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  f the metadata i
38460 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72  s still valid or
38470 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20  .** NULL if the 
38480 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
38490 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  n discarded..** 
384a0 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c  ^After each call
384b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
384c0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
384d0 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20   where X is not 
384e0 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  NULL,.** SQLite 
384f0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
38500 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
38510 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d  ion X with param
38520 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a  eter P exactly.*
38530 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65  * once, when the
38540 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73   metadata is dis
38550 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74  carded..** SQLit
38560 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73  e is free to dis
38570 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74  card the metadat
38580 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69  a at any time, i
38590 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a  ncluding: <ul>.*
385a0 2a 20 3c 6c 69 3e 20 5e 28 77 68 65 6e 20 74 68  * <li> ^(when th
385b0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
385c0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
385d0 65 72 20 63 68 61 6e 67 65 73 29 5e 2c 20 6f 72  er changes)^, or
385e0 0a 2a 2a 20 3c 6c 69 3e 20 5e 28 77 68 65 6e 20  .** <li> ^(when 
385f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
38600 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
38610 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
38620 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  led for the.**  
38630 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e      SQL statemen
38640 74 29 5e 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  t)^, or.** <li> 
38650 5e 28 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  ^(when sqlite3_s
38660 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20  et_auxdata() is 
38670 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e  invoked again on
38680 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
38690 20 20 20 70 61 72 61 6d 65 74 65 72 29 5e 2c 20     parameter)^, 
386a0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5e 28 64 75 72  or.** <li> ^(dur
386b0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
386c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
386d0 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e  data() call when
386e0 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20   a memory .**   
386f0 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72     allocation er
38700 72 6f 72 20 6f 63 63 75 72 73 2e 29 5e 20 3c 2f  ror occurs.)^ </
38710 75 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ul>.**.** Note t
38720 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69  he last bullet i
38730 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54  n particular.  T
38740 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20  he destructor X 
38750 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  in .** sqlite3_s
38760 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
38770 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  ,X) might be cal
38780 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  led immediately,
38790 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73   before the.** s
387a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
387b0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  ta() interface e
387c0 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65  ven returns.  He
387d0 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  nce sqlite3_set_
387e0 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f  auxdata().** sho
387f0 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20