/ Hex Artifact Content
Login

Artifact 2683a291ed8db5228024267be6421f0de507b80e:


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 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  on, sqlite3_sour
1230: 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ceid.**.** These
1240: 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76   interfaces prov
1250: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
1260: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
1270: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
1280: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  ,.** [SQLITE_VER
1290: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e  SION_NUMBER], an
12a0: 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  d [SQLITE_SOURCE
12b0: 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73  _ID] C preproces
12c0: 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75  sor macros.** bu
12d0: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
12e0: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72   with the librar
12f0: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  y instead of the
1300: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e   header file.  ^
1310: 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f  (Cautious.** pro
1320: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69  grammers might i
1330: 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20  nclude assert() 
1340: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
1350: 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  eir application 
1360: 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61  to.** verify tha
1370: 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  t values returne
1380: 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72  d by these inter
1390: 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20  faces match the 
13a0: 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65  macros in.** the
13b0: 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75   header, and thu
13c0: 73 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  s ensure that th
13d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
13e0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
13f0: 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61  h matching libra
1400: 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69  ry and header fi
1410: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  les..**.** <bloc
1420: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1430: 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f  assert( sqlite3_
1440: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1450: 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53  r()==SQLITE_VERS
1460: 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a  ION_NUMBER );.**
1470: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1480: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1490: 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  (),SQLITE_SOURCE
14a0: 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73  _ID)==0 );.** as
14b0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
14c0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
14d0: 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ),SQLITE_VERSION
14e0: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65  )==0 );.** </pre
14f0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1500: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1510: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1520: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f  ring constant co
1530: 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20  ntains the text 
1540: 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  of [SQLITE_VERSI
1550: 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e  ON].** macro.  ^
1560: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
1570: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f  ersion() functio
1580: 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  n returns a poin
1590: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f  ter to the.** to
15a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72   the sqlite3_ver
15b0: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f  sion[] string co
15c0: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c  nstant.  The sql
15d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
15e0: 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ).** function is
15f0: 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73   provided for us
1600: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20  e in DLLs since 
1610: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c  DLL users usuall
1620: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a  y do not have.**
1630: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
1640: 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  o string constan
1650: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
1660: 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  L.  ^The.** sqli
1670: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1680: 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e  umber() function
1690: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
16a0: 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20  ger equal to.** 
16b0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
16c0: 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73  NUMBER].  ^The s
16d0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
16e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
16f0: 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ns .** a pointer
1700: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   to a string con
1710: 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75  stant whose valu
1720: 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  e is the same as
1730: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1740: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72  _SOURCE_ID] C pr
1750: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1760: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1770: 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  : [sqlite_versio
1780: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
1790: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
17a0: 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
17b0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
17c0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
17d0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
17e0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
17f0: 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  d);.const char *
1800: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1810: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
1820: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1830: 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a  umber(void);../*
1840: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1850: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43  n-Time Library C
1860: 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f  ompilation Optio
1870: 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a  ns Diagnostics.*
1880: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1890: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
18a0: 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  used() function 
18b0: 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a  returns 0 or 1 .
18c0: 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68  ** indicating wh
18d0: 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66  ether the specif
18e0: 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64  ied option was d
18f0: 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f  efined at .** co
1900: 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68  mpile time.  ^Th
1910: 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78  e SQLITE_ prefix
1920: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
1930: 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74  from the .** opt
1940: 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20  ion name passed 
1950: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  to sqlite3_compi
1960: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e  leoption_used().
1970: 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71    .**.** ^The sq
1980: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1990: 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69  ion_get() functi
19a0: 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74  on allows iterat
19b0: 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  ing.** over the 
19c0: 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20  list of options 
19d0: 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65  that were define
19e0: 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  d at compile tim
19f0: 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e  e by.** returnin
1a00: 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69  g the N-th compi
1a10: 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73  le time option s
1a20: 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73  tring.  ^If N is
1a30: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a   out of range,.*
1a40: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
1a50: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65  eoption_get() re
1a60: 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1a70: 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49  nter.  ^The SQLI
1a80: 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69  TE_ .** prefix i
1a90: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61  s omitted from a
1aa0: 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  ny strings retur
1ab0: 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ned by .** sqlit
1ac0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1ad0: 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53  _get()..**.** ^S
1ae0: 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64  upport for the d
1af0: 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69  iagnostic functi
1b00: 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ons sqlite3_comp
1b10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1b20: 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
1b30: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b40: 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  t() may be omitt
1b50: 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67  ed by specifying
1b60: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1b70: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1b80: 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f  ION_DIAGS] optio
1b90: 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  n at compile tim
1ba0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
1bb0: 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  o: SQL functions
1bc0: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1bd0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61  option_used()] a
1be0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f  nd.** [sqlite_co
1bf0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1c00: 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70  )] and the [comp
1c10: 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67  ile_options prag
1c20: 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ma]..*/.#ifndef 
1c30: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1c40: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a  ILEOPTION_DIAGS.
1c50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1c60: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63  ileoption_used(c
1c70: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e  onst char *zOptN
1c80: 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  ame);.const char
1c90: 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c   *sqlite3_compil
1ca0: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20  eoption_get(int 
1cb0: 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  N);.#endif../*.*
1cc0: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
1cd0: 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c   To See If The L
1ce0: 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64  ibrary Is Thread
1cf0: 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  safe.**.** ^The 
1d00: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1d10: 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  fe() function re
1d20: 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e  turns zero if an
1d30: 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c  d only if.** SQL
1d40: 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ite was compiled
1d50: 20 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63   with mutexing c
1d60: 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20  ode omitted due 
1d70: 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  to the.** [SQLIT
1d80: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f  E_THREADSAFE] co
1d90: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1da0: 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30  n being set to 0
1db0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  ..**.** SQLite c
1dc0: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77  an be compiled w
1dd0: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d  ith or without m
1de0: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a  utexes.  When.**
1df0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1e00: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72  EADSAFE] C prepr
1e10: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73  ocessor macro is
1e20: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
1e30: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
1e40: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
1e50: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
1e60: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
1e70: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1e80: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
1e90: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
1ea0: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
1eb0: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
1ec0: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
1ed0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
1ee0: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
1ef0: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
1f00: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
1f10: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
1f20: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
1f30: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
1f40: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1f50: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1f60: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1f70: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1f80: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1f90: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1fa0: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1fb0: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1fc0: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nabled..** ^The 
1fd0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
1fe0: 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20   is for mutexes 
1ff0: 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  to be enabled..*
2000: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2010: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2020: 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  by an applicatio
2030: 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  n to make sure t
2040: 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69  hat the.** versi
2050: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61  on of SQLite tha
2060: 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20  t it is linking 
2070: 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70  against was comp
2080: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
2090: 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67   desired setting
20a0: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
20b0: 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72  THREADSAFE] macr
20c0: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  o..**.** This in
20d0: 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70  terface only rep
20e0: 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  orts on the comp
20f0: 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73  ile-time mutex s
2100: 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65  etting.** of the
2110: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2120: 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53  AFE] flag.  If S
2130: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2140: 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45  d with.** SQLITE
2150: 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72  _THREADSAFE=1 or
2160: 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73   =2 then mutexes
2170: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
2180: 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63  default but.** c
2190: 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70  an be fully or p
21a0: 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65  artially disable
21b0: 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74  d using a call t
21c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
21d0: 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65  g()].** with the
21e0: 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43   verbs [SQLITE_C
21f0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
2200: 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  AD], [SQLITE_CON
2210: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
2220: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2230: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
2240: 44 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72  D].  ^(The retur
2250: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a  n value of the.*
2260: 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  * sqlite3_thread
2270: 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  safe() function 
2280: 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63  shows only the c
2290: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74  ompile-time sett
22a0: 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64  ing of.** thread
22b0: 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79   safety, not any
22c0: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65   run-time change
22d0: 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  s to that settin
22e0: 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c  g made by.** sql
22f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49  ite3_config(). I
2300: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2310: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2320: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72  from sqlite3_thr
2330: 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20  eadsafe().** is 
2340: 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c  unchanged by cal
2350: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2360: 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  nfig().)^.**.** 
2370: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
2380: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
2390: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
23a0: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
23b0: 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
23c0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
23d0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
23e0: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
23f0: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
2400: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
2410: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2420: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
2430: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
2440: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
2450: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
2460: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
2470: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
2480: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
2490: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
24a0: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
24b0: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
24c0: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
24d0: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
24e0: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
24f0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
2500: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2510: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
2520: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2530: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
2540: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
2550: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
2560: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61  e3_close()].** a
2570: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
2580: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20  e_v2()] are its 
2590: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68  destructors.  Th
25a0: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
25b0: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  er.** interfaces
25c0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
25d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
25e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
25f0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2600: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2610: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
2620: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
2630: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
2640: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
2650: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
2660: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2670: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
2680: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2690: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
26a0: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
26b0: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
26c0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
26d0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
26e0: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
26f0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
2700: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
2710: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
2720: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
2730: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
2740: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
2750: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
2760: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2770: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2780: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
2790: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
27a0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
27b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
27c0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
27d0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
27e0: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
27f0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
2800: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
2810: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2820: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2830: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
2840: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2850: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
2860: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
2870: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
2880: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
2890: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
28a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
28b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
28c0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
28d0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
28e0: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
28f0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
2900: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
2910: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
2920: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2930: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
2940: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2950: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2960: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2970: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
2980: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
2990: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
29a0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
29b0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
29c0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
29d0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
29e0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
29f0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2a00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2a10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2a20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2a30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2a40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2a50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2a60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2a70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2a80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2a90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2aa0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2ab0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2ac0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2ad0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2ae0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2af0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2b00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2b10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2b20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2b30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2b40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2b50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2b60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2b70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2b80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2b90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2ba0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54  tion.** DESTRUCT
2bb0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
2bc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2bd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2be0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
2bf0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
2c00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
2c10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2c20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2c30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2c40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2c50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
2c60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
2c70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2c80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
2c90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
2ca0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
2cb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
2cc0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2cd0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
2ce0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cf0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
2d00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2d10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
2d20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
2d30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2d40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
2d50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
2d60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
2d70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2d80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
2d90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
2da0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
2db0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2dc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
2dd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2de0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2df0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
2e00: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2e10: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
2e20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e30: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
2e40: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
2e50: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
2e60: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
2e70: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
2e80: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
2e90: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ea0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
2eb0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
2ec0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
2ed0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
2ee0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ef0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
2f00: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
2f10: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
2f20: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
2f30: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
2f40: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
2f50: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
2f60: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
2f70: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
2f80: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
2f90: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
2fa0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2fb0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
2fc0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
2fd0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
2fe0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
2ff0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
3000: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3010: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
3020: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
3030: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
3040: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3050: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
3060: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
3070: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
3080: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
3090: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
30a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
30b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
30c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
30d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
30f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
3100: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
3110: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3120: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
3130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3140: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3150: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
3160: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
3170: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3180: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3190: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
31a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
31b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
31c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
31d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
31e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
31f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3200: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3210: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3220: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3230: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3240: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3250: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3260: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3270: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3280: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3290: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
32a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
32c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
32d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
32e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
32f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3300: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3310: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3320: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3330: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3340: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3350: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3360: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3370: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3380: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3390: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
33a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
33b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
33c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
33d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
33e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
33f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
3400: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33  close_v2(sqlite3
3410: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
3420: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
3430: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
3440: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
3450: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
3460: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
3470: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
3480: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
3490: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
34a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
34b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
34c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
34d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
34e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
34f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
3500: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
3510: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f  terface.** METHO
3520: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
3530: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3540: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3550: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3560: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3570: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3580: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3590: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
35a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
35b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
35c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
35d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
35e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
35f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3600: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3610: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3620: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3630: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3640: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3650: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3660: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3670: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3680: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3690: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
36a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
36b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
36c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
36e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
36f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3700: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3710: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3720: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3730: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3740: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3750: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3760: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3770: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3780: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3790: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
37a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
37b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
37c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
37d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
37e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
37f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3800: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3810: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3820: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3830: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3840: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3850: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3860: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3870: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3880: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3890: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
38a0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
38b0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
38c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
38d0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
38e0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
38f0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3900: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3910: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3920: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3930: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3940: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3950: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3960: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3970: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3980: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3990: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
39a0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
39b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
39c0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
39d0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
39e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
39f0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3a00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3a10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3a20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3a30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3a40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3a50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3a60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3a70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3a80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
3a90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
3aa0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
3ab0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3ac0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
3ad0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3af0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
3b00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
3b10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
3b20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
3b30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
3b40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
3b50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
3b60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
3b70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
3b80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
3b90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
3ba0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3bb0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
3bc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
3bd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
3be0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
3bf0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
3c00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
3c10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
3c20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
3c30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
3c40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3c50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3c60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
3c70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
3c80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
3c90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
3ca0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3cb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3cc0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
3cd0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3ce0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3cf0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
3d00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
3d10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
3d20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
3d30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
3d40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
3d50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
3d60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
3d70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
3d80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
3d90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3da0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
3db0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
3dc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3dd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
3de0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3df0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
3e00: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
3e10: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
3e20: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
3e30: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
3e40: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
3e50: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
3e60: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3e70: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
3e80: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
3e90: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
3ea0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3eb0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
3ec0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
3ed0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
3ee0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
3ef0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
3f00: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
3f10: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
3f20: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
3f30: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
3f40: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
3f50: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
3f60: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
3f70: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
3f80: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
3f90: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
3fa0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
3fb0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
3fc0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
3fd0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3fe0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
3ff0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
4000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4010: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
4020: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4030: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
4040: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4050: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4060: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4070: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4080: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4090: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
40a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
40b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
40c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
40d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
40e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
40f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
4100: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
4110: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
4120: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4130: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4140: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4150: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
4160: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4170: 2a 2c 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 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
41a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
41b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st 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 20 2f 2a 20 53 51 4c 20 74          /* SQL t
41e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
41f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4200: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4210: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4220: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4230: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  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 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4270: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4280: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4290: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
42c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
42d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
42e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
42f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4300: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4310: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
4320: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4330: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4340: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4350: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4360: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4370: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4380: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4390: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
43a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
43b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
43c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
43d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
43e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
43f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4400: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
4410: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4420: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4430: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4440: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4450: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4470: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4480: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
4490: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
44a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
44b0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
44c0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
44d0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
44e0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
44f0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
4500: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4510: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4520: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4530: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4540: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4550: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4560: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4580: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4590: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
45a0: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
45b0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
45c0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
45d0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
45e0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
45f0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4610: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4620: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4650: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4660: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4670: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4680: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4690: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
46a0: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
46b0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
46c0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
46f0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
4700: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4710: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4720: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4730: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4740: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4750: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4760: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4770: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4780: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4790: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
47a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
47b0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
47c0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
47d0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
47e0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
47f0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
4800: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4810: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4820: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4830: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4840: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4860: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4870: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4880: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
48a0: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
48b0: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
48c0: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
48d0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
48e0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
48f0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4900: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4910: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4920: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4930: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4940: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4950: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4960: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4970: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4980: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4990: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
49b0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
49c0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
49d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
49e0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
49f0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4a00: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4a10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a20: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4a30: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4a40: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4a50: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4a70: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4a80: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4a90: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4aa0: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4ab0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
4ac0: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
4ad0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
4ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4af0: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
4b00: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
4b10: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
4b20: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
4b30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b40: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
4b50: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
4b60: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
4b70: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4b80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4b90: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f  TICE      27   /
4ba0: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20  * Notifications 
4bb0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4bc0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4bd0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20  LITE_WARNING    
4be0: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67   28   /* Warning
4bf0: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4c00: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4c10: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
4c20: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
4c30: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
4c40: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
4c50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4c60: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
4c70: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
4c80: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
4c90: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
4ca0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
4cb0: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
4cc0: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
4cd0: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
4ce0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4cf0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4d00: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4d10: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4d20: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4d30: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4d40: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4d50: 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a  e of 30 integer.
4d60: 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  ** [result codes
4d70: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4d80: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4d90: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4da0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4db0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4dc0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4dd0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4de0: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4df0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4e00: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4e10: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4e20: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4e30: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4e40: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4e50: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4e60: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61  ersion 3.3.8 [da
4e70: 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61  teof:3.3.8].** a
4e80: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
4e90: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
4ea0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
4eb0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
4ec0: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
4ed0: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
4ee0: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
4ef0: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
4f00: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
4f10: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4f20: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4f30: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4f40: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4f50: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4f60: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4f70: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4f80: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
4f90: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
4fa0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
4fb0: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
4fc0: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
4fd0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
4fe0: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
4ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5000: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
5010: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5020: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
5030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5040: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
5050: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5060: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
5070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5080: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
5090: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50a0: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
50b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50c0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
50d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50e0: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
50f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5100: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
5110: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5120: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5130: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
5140: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
5150: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5160: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
5170: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
5180: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
5190: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51a0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
51b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
51c0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
51d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
51e0: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
51f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
5200: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5210: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
5220: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5230: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
5240: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
5250: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
5260: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5270: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
5280: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
5290: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
52a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
52c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
52d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
52e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
5300: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
5310: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
5320: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5330: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
5340: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
5350: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
5360: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5370: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
5380: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5390: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
53a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
53c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
53d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
53e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
5400: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
5410: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
5420: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5430: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
5440: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
5450: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
5460: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5470: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
5480: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
5490: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
54a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
54c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
54d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
54e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
5500: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
5510: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
5520: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5530: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
5540: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5550: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
5560: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5570: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
5580: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
5590: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
55a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
55c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
55d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
55e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
5600: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
5610: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
5620: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5630: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
5640: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
5650: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
5660: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5670: 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45  LITE_IOERR_VNODE
5680: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5690: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37  LITE_IOERR | (27
56a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20  LITE_IOERR_AUTH 
56c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
56d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38  LITE_IOERR | (28
56e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56f0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
5700: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
5710: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
5720: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5730: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
5740: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
5750: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
5760: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5770: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
5780: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
5790: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
57a0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
57b0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
57c0: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
57d0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
57e0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
57f0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5800: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
5810: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5820: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
5830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5840: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
5850: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5860: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
5870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5880: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
5890: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
58a0: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
58b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58c0: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
58d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
58e0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
58f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5900: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5910: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5920: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5930: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5940: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5950: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5960: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5970: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5980: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
5990: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
59a0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
59b0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
59c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
59d0: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
59e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
59f0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5a00: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5a10: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5a20: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5a30: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5a40: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5a50: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
5a60: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5a70: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a90: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
5aa0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
5ab0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5ac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ad0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5ae0: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5af0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5b00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5b20: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5b30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b40: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5b50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5b60: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5b70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5b80: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5b90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ba0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5bb0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5bc0: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5be0: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5bf0: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5c00: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5c20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5c30: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5c40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5c50: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5c60: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5c70: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5c80: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c90: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5cb0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
5cc0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5cd0: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
5ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5cf0: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
5d00: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
5d10: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
5d40: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
5d50: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
5d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d70: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
5d80: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
5d90: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
5da0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5db0: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20  _AUTH_USER      
5dc0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5dd0: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a  _AUTH | (1<<8)).
5de0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5df0: 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54  K_LOAD_PERMANENT
5e00: 4c 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f  LY     (SQLITE_O
5e10: 4b 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  K | (1<<8))../*.
5e20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5e30: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5e40: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5e50: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5e60: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5e70: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5e80: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5e90: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5ea0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5eb0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5ec0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5ed0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5ee0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5ef0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5f00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5f10: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5f20: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5f30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5f40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5f50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5f60: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5f70: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5f80: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5f90: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5fa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5fb0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5fc0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5fd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fe0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ff0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
6000: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
6010: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
6020: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6030: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
6040: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
6050: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
6060: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6070: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
6080: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
6090: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
60a0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
60c0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
60d0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
60e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
60f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
6110: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
6120: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
6130: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6140: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6150: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6160: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6170: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6180: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6190: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
61a0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
61b0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
61c0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
61d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
61e0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
61f0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
6200: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6220: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6230: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6240: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6260: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6270: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6280: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6290: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
62a0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
62b0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
62c0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
62d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
62e0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
62f0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
6300: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6310: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6320: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
6330: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6340: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6350: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6360: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6370: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6380: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6390: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
63a0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
63b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
63c0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
63d0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
63e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
63f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6400: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6410: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6420: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
6430: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6440: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6450: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6460: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6470: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6480: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6490: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
64a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
64b0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
64c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
64d0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
64e0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
64f0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6500: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6510: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6520: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6530: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6540: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6550: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6560: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6570: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6580: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6590: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
65a0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
65b0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
65c0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
65d0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
65e0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
65f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6600: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6610: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6620: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6630: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6640: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6650: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6660: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6670: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6680: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6690: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
66a0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
66b0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
66c0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
66d0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
66e0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
66f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6700: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6710: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6720: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6730: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6740: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6750: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6760: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6770: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6780: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6790: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
67a0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
67b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
67c0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
67d0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
67e0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
67f0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6800: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6810: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6820: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6830: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6840: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6850: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6860: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6870: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6880: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6890: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
68a0: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
68b0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
68c0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
68d0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
68e0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
68f0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6900: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6910: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6920: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6930: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6940: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6950: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6960: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6970: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6980: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
6990: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
69a0: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
69b0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
69c0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
69d0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
69e0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
69f0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6a00: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6a10: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6a20: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6a30: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6a40: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6a50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a60: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6a70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6a80: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6a90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6aa0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6ab0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6ac0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6ad0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6ae0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6af0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b20: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6b30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b40: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6b50: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6b60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b70: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6b80: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b90: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6ba0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6bb0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6bc0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6be0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6bf0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c00: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6c10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6c20: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6c30: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6c40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c50: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6c60: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6c70: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c80: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6c90: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6ca0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6cb0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6cc0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6cd0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6ce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6cf0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6d00: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6d10: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6d20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6d30: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6d40: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6d50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6d60: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6d70: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6d80: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6d90: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6da0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6db0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6dc0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6dd0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6de0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6df0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6e00: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6e10: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6e20: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6e30: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6e50: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6e60: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6e70: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6e80: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6e90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6ea0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6eb0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6ec0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6ed0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6ee0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6ef0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6f00: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6f10: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6f20: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6f30: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6f40: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6f50: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6f60: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6f70: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6f80: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6f90: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6fa0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6fb0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6fc0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6fd0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6fe0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6ff0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
7000: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
7010: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
7020: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
7030: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
7040: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
7050: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
7060: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
7070: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
7080: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
7090: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
70a0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
70b0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
70c0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
70d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
70e0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
70f0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
7100: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7110: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7120: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7130: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7140: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7150: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7160: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
7170: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
7180: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
7190: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
71a0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
71b0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
71c0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
71d0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
71e0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
71f0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
7200: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7210: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7220: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7230: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7240: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7250: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7260: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
7270: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
7280: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
7290: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
72a0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
72b0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
72c0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
72d0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
72e0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
72f0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
7300: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7310: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7320: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7330: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7340: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7350: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7360: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7370: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
7380: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
7390: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
73a0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
73b0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
73c0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
73d0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
73e0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
73f0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7420: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7430: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7440: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7450: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7460: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
7470: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7480: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
7490: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
74a0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
74b0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
74c0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
74d0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
74e0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
74f0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
7500: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7510: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7520: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7530: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7540: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7550: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7560: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
7570: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
7580: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7590: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
75a0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
75b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
75c0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
75d0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
75e0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
75f0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
7600: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7610: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7620: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7630: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7640: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7650: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7660: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7670: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
7680: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7690: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
76a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
76b0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
76c0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
76d0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
76e0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
76f0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7700: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7710: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7720: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7730: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7740: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7750: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7760: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7770: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
7780: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7790: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
77a0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
77b0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
77c0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
77d0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
77e0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
77f0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
7800: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7810: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7820: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7830: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7840: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7850: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7860: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7870: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
7880: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7890: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
78a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
78b0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
78c0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
78d0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
78e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
78f0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
7900: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7910: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7920: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7930: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7940: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7950: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7960: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
7970: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7980: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7990: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
79a0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
79b0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
79c0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
79d0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
79e0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
79f0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
7a00: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7a10: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7a20: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7a30: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7a40: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7a50: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7a60: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7a70: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7a80: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7a90: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7aa0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
7ab0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7ac0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7ad0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
7ae0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
7af0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
7b00: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7b10: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7b20: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7b30: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7b40: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7b50: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7b60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7b70: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7b80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7b90: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7ba0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7bb0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7bc0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7bd0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7be0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7bf0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7c00: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7c10: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7c20: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7c30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7c40: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7c50: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7c60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7c70: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7c80: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7c90: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7ca0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7cb0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7cc0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7cd0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7ce0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7cf0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7d00: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7d10: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7d20: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7d30: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7d40: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7d50: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7d60: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7d70: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7d80: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7d90: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7da0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7db0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7dc0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7dd0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7de0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7df0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7e00: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7e10: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7e20: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7e30: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7e40: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7e50: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7e60: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7e70: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7e80: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7e90: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7ea0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7eb0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7ec0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7ed0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7ee0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7ef0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7f00: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7f10: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7f20: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7f30: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7f40: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7f50: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7f60: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7f70: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7f80: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7f90: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7fa0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7fb0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7fc0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7fd0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
7fe0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
7ff0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
8000: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
8010: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
8020: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
8030: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
8040: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
8050: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
8060: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
8070: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
8080: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
8090: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
80a0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
80b0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
80c0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
80d0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
80e0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
80f0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8100: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8110: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8120: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8130: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8140: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8150: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8160: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
8170: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
8180: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
8190: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
81a0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
81b0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
81c0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
81d0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
81e0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
81f0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8200: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8210: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8220: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8230: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8240: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8250: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8260: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8270: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8280: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
8290: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82a0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
82b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82c0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
82d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82e0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
82f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8300: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8310: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8320: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8330: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8340: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8350: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8360: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8370: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8380: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
8390: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
83a0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
83b0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
83c0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
83d0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
83e0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
83f0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8400: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8410: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8420: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8430: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8440: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8450: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8460: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8470: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8480: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8490: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
84a0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
84b0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
84c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
84d0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
84e0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
84f0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8500: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8510: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8520: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8530: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8540: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8550: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8560: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8570: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8580: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8590: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
85a0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
85b0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
85c0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
85d0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
85e0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
85f0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
8600: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8620: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8630: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8640: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8650: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8660: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8670: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8680: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8690: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
86a0: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
86b0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
86c0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
86d0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
86e0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
86f0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
8700: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8710: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8720: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8730: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8740: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8750: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8760: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8770: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8780: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8790: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
87a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
87b0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
87c0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
87d0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
87e0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
87f0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
8800: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8810: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8820: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8830: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8840: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8850: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8860: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8870: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8880: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8890: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
88a0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
88b0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
88c0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
88d0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
88e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
88f0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8900: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8910: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8920: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8930: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8940: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8950: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8960: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8970: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8980: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8990: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
89a0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
89b0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
89c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
89d0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
89e0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
89f0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8a00: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8a10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8a20: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8a30: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8a40: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8a50: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8a60: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8a70: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8a80: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8a90: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8aa0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8ab0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8ac0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8ad0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8ae0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8af0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8b00: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8b10: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8b20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8b30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8b40: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8b50: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8b60: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8b70: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8b80: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8b90: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8ba0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8bb0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8bc0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8bd0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8be0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8bf0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8c00: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8c10: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8c20: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8c30: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8c40: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8c50: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8c60: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8c70: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8c80: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8c90: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8ca0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8cb0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8cc0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8cd0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8ce0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8cf0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8d00: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8d10: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8d20: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8d30: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8d40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8d50: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8d60: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8d70: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8d80: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8d90: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8da0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8db0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8dc0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8dd0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8de0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8df0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8e00: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8e20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8e30: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8e50: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8e60: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8e70: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8e80: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8e90: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8ea0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8eb0: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8ec0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8ed0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8ee0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8ef0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8f00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8f10: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8f20: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8f30: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8f40: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8f50: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8f60: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8f70: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8f80: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8f90: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8fa0: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8fb0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8fc0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8fd0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8fe0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8ff0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
9000: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
9010: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
9020: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
9030: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
9040: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9050: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
9060: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
9070: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
9080: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
9090: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
90a0: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
90b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
90c0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
90d0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
90e0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
90f0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9100: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
9110: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9120: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9130: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9140: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9150: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9160: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9170: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9180: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9190: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
91a0: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
91b0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
91c0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
91d0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
91e0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
91f0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
9200: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
9210: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9220: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9230: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9240: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9250: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9260: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9270: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9280: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9290: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
92a0: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
92b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
92c0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
92d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
92e0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
92f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9300: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9310: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9320: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9330: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9340: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9350: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9360: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9370: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9380: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9390: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
93a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
93b0: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
93c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
93d0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
93e0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
93f0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9400: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9410: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9420: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9430: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
9440: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
9450: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
9460: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
9470: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
9480: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
9490: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
94a0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
94b0: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
94c0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
94d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
94e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
94f0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
9500: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
9510: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9520: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
9530: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9540: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
9550: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
9560: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9570: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
9580: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
9590: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
95a0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
95b0: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
95c0: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
95d0: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
95e0: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
95f0: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
9600: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
9610: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
9620: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
9630: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
9640: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
9650: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
9660: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
9670: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
9680: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
9690: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
96a0: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
96b0: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
96c0: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
96d0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
96e0: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
96f0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9700: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
9710: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
9720: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
9730: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
9740: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
9750: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
9760: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
9770: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
9780: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
9790: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
97a0: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
97b0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
97c0: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
97d0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
97e0: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
97f0: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
9800: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
9810: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9820: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9830: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9840: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
9850: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
9860: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9870: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9880: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9890: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
98a0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
98b0: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
98c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
98d0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
98e0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
98f0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9900: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
9910: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9920: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
9930: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
9940: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
9950: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
9960: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
9970: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
9980: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
9990: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
99a0: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
99b0: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
99c0: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
99d0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
99e0: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
99f0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9a00: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9a10: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9a20: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
9a30: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9a40: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9a50: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9a60: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9a70: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9a80: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9a90: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9aa0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9ab0: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9ac0: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9ad0: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9ae0: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9af0: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9b00: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
9b10: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
9b20: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
9b30: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
9b40: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
9b50: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
9b60: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
9b70: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
9b80: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9b90: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9ba0: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9bb0: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9bc0: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9bd0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9be0: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9bf0: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9c00: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
9c10: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
9c20: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
9c30: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
9c40: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
9c50: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
9c60: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
9c70: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
9c80: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9c90: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9ca0: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9cb0: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9cc0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9cd0: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9ce0: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9cf0: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9d00: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
9d10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
9d20: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9d30: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
9d40: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
9d50: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
9d60: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
9d70: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
9d80: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
9d90: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
9da0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
9db0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
9dc0: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
9dd0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
9de0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
9df0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
9e00: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
9e10: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
9e20: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
9e30: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
9e40: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
9e50: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
9e60: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
9e70: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
9e80: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
9e90: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
9ea0: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
9eb0: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
9ec0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9ed0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9ee0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9ef0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9f00: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
9f10: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9f20: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9f30: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
9f40: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
9f50: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
9f60: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
9f70: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
9f80: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
9f90: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
9fa0: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
9fb0: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
9fc0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
9fd0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
9fe0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
9ff0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
a000: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
a010: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
a020: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
a030: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
a040: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
a050: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
a060: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
a070: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
a080: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
a090: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
a0a0: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
a0b0: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a0c0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a0d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a0e0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a0f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a100: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
a110: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a120: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
a130: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
a140: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
a150: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
a160: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a170: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a180: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a190: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a1a0: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a1b0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a1c0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a1d0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a1e0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
a1f0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
a200: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
a210: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
a220: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a230: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a240: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a250: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a260: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
a270: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
a280: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a290: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a2a0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a2b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a2c0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a2d0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a2e0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a2f0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a300: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
a310: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
a320: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
a330: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
a340: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
a350: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
a360: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
a370: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
a380: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
a390: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
a3a0: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
a3b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a3c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a3d0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a3e0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a3f0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a400: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a410: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a420: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
a430: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
a440: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
a450: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
a460: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a470: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a480: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a490: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a4a0: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
a4b0: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
a4c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a4d0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
a4e0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a4f0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a500: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
a510: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
a520: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
a530: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
a540: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
a550: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
a560: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
a570: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
a580: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
a590: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
a5a0: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
a5b0: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
a5c0: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
a5d0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
a5e0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
a5f0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
a600: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a610: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
a620: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a630: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
a640: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
a650: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
a660: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
a670: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
a680: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
a690: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
a6a0: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
a6b0: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
a6c0: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
a6d0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a6e0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
a6f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
a700: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
a710: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
a720: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
a730: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
a740: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
a750: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a760: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
a770: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
a780: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
a790: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
a7a0: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
a7b0: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
a7c0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
a7d0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
a7e0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
a7f0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
a800: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
a810: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
a820: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
a830: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a840: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
a850: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
a860: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
a870: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
a880: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
a890: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
a8a0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
a8b0: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
a8c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a8d0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
a8e0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
a8f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a900: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
a910: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
a920: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
a930: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
a940: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
a950: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
a960: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
a970: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
a980: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a990: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
a9a0: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
a9b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
a9c0: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
a9d0: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
a9e0: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
a9f0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
aa00: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
aa10: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
aa20: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
aa30: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
aa40: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
aa50: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
aa60: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
aa70: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
aa80: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
aa90: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
aaa0: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
aab0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
aac0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
aad0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aae0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
aaf0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
ab00: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
ab10: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
ab20: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
ab30: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
ab40: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
ab50: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
ab60: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
ab70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ab80: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ab90: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
aba0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
abb0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
abc0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
abd0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
abe0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
abf0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
ac00: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
ac10: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
ac20: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
ac30: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
ac40: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
ac50: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
ac60: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
ac70: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
ac80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ac90: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
aca0: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
acb0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
acc0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
acd0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
ace0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
acf0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
ad00: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
ad10: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
ad20: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
ad30: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
ad40: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
ad50: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
ad60: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
ad70: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
ad80: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
ad90: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
ada0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
adb0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
adc0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
add0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
ade0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
adf0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
ae00: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
ae10: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ae20: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
ae30: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
ae40: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
ae50: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
ae60: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
ae70: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
ae80: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
ae90: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
aea0: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
aeb0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
aec0: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
aed0: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
aee0: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
aef0: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
af00: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
af10: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
af20: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
af30: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
af40: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
af50: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
af60: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
af70: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
af80: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
af90: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
afa0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
afb0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
afc0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
afd0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
afe0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
aff0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
b000: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
b010: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
b020: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
b030: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b040: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b050: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
b060: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
b070: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
b080: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
b090: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
b0a0: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
b0b0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b0c0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b0d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b0e0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b0f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b100: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
b110: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
b120: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
b130: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
b140: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
b150: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
b160: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
b170: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
b180: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
b190: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
b1a0: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
b1b0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
b1c0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
b1d0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
b1e0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
b1f0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
b200: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
b210: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
b220: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
b230: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
b240: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
b250: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
b260: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
b270: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
b280: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
b290: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
b2a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
b2b0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
b2c0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
b2d0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
b2e0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
b2f0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
b300: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
b310: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
b320: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
b330: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
b340: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
b350: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
b360: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
b370: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
b380: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b390: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b3a0: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
b3b0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
b3c0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
b3d0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b3e0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
b3f0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
b400: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
b410: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b420: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
b430: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
b440: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
b450: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
b460: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b470: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
b480: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
b490: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
b4a0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b4b0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
b4c0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
b4d0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
b4e0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
b4f0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
b500: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b510: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
b520: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
b530: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
b540: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
b550: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
b560: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
b570: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
b580: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b590: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b5a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b5b0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
b5c0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
b5d0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
b5e0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
b5f0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
b600: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b610: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b620: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b630: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b640: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b650: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b660: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b670: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b680: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b690: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b6a0: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b6b0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b6c0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b6d0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b6e0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b6f0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b700: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b710: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b720: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b730: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b740: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b750: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b760: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b770: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b780: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b790: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b7a0: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b7b0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b7c0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b7d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b7e0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b7f0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b800: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
b810: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
b820: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
b830: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
b840: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
b850: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
b860: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
b870: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
b880: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
b890: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b8a0: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
b8b0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
b8c0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
b8d0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
b8e0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
b8f0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
b900: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
b910: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
b920: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
b930: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
b940: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
b950: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
b960: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
b970: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
b980: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
b990: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b9a0: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
b9b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b9c0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
b9d0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
b9e0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
b9f0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
ba00: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
ba10: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
ba20: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
ba30: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
ba40: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
ba50: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
ba60: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
ba70: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
ba80: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
ba90: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
baa0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bab0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bac0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
bad0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bae0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
baf0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
bb00: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
bb10: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
bb20: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
bb30: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
bb40: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
bb50: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
bb60: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
bb70: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
bb80: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
bb90: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
bba0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
bbb0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
bbc0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
bbd0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
bbe0: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
bbf0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bc00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
bc10: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
bc20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
bc30: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
bc40: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
bc50: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
bc60: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
bc70: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
bc80: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
bc90: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
bca0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
bcb0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
bcc0: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
bcd0: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
bce0: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
bcf0: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
bd00: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
bd10: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
bd20: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
bd30: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
bd40: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
bd50: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
bd60: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
bd70: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
bd80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
bd90: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
bda0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
bdb0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
bdc0: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
bdd0: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
bde0: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
bdf0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
be00: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
be10: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
be20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
be30: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
be40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
be50: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
be60: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
be70: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
be80: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
be90: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
bea0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
beb0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
bec0: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
bed0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
bee0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
bef0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bf00: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
bf10: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
bf20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bf30: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
bf40: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
bf50: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
bf60: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
bf70: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
bf80: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
bf90: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
bfa0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
bfb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
bfc0: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
bfd0: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
bfe0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
bff0: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
c000: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
c010: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
c020: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
c030: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
c040: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
c050: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
c060: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
c070: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
c080: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
c090: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
c0a0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
c0b0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
c0c0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c0d0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
c0e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
c0f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c100: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
c110: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
c120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c130: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
c140: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
c150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c160: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
c170: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
c180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c190: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
c1a0: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
c1b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c1c0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
c1d0: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
c1e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c1f0: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
c200: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
c210: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c220: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
c230: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
c240: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
c250: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
c260: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
c270: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
c280: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
c290: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
c2a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c2b0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
c2c0: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
c2d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c2e0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
c2f0: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
c300: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c310: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
c320: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
c330: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c340: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c350: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
c360: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
c370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c380: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
c390: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
c3a0: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
c3b0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
c3c0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
c3d0: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
c3e0: 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20  ../* deprecated 
c3f0: 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  names */.#define
c400: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
c410: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
c420: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
c430: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
c440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
c450: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c460: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
c470: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
c480: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
c490: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
c4a0: 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f           SQLITE_
c4b0: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
c4c0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
c4d0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
c4e0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
c4f0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
c500: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
c510: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
c520: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
c530: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
c540: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
c550: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
c560: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
c570: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
c580: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
c590: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
c5a0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
c5b0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
c5c0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
c5d0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
c5e0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
c5f0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
c600: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
c610: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
c620: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
c630: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
c640: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
c650: 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c  API3REF: Loadabl
c660: 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e  e Extension Thun
c670: 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  k.**.** A pointe
c680: 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20  r to the opaque 
c690: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
c6a0: 69 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69  ines structure i
c6b0: 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  s passed as.** t
c6c0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
c6d0: 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e  er to entry poin
c6e0: 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20  ts of [loadable 
c6f0: 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68  extensions].  Th
c700: 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  is.** structure 
c710: 6d 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65  must be typedefe
c720: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f  d in order to wo
c730: 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c  rk around compil
c740: 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f  er warnings.** o
c750: 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73  n some platforms
c760: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
c770: 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  uct sqlite3_api_
c780: 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33  routines sqlite3
c790: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a  _api_routines;..
c7a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c7b0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
c7c0: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
c7d0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
c7e0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
c7f0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
c800: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
c810: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
c820: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
c830: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
c840: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
c850: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
c860: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
c870: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
c880: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
c890: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
c8a0: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
c8b0: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
c8c0: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
c8d0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
c8e0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
c8f0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
c900: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
c910: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
c920: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
c930: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
c940: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
c950: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
c960: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
c970: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
c980: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
c990: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
c9a0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
c9b0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c9c0: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
c9d0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
c9e0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
c9f0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
ca00: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
ca10: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
ca20: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
ca30: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
ca40: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
ca50: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
ca60: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
ca70: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
ca80: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
ca90: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
caa0: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
cab0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
cac0: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
cad0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
cae0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
caf0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
cb00: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
cb10: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
cb20: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
cb30: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
cb40: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
cb50: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
cb60: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
cb70: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
cb80: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
cb90: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
cba0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
cbb0: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
cbc0: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
cbd0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
cbe0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
cbf0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
cc00: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
cc10: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
cc20: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
cc30: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
cc40: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
cc50: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
cc60: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
cc70: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
cc80: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
cc90: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
cca0: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
ccb0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
ccc0: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
ccd0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
cce0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
ccf0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
cd00: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
cd10: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
cd20: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
cd30: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
cd40: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
cd50: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
cd60: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
cd70: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
cd80: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
cd90: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
cda0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
cdb0: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
cdc0: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
cdd0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
cde0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
cdf0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
ce00: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
ce10: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
ce20: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
ce30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
ce40: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
ce50: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
ce60: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
ce70: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
ce80: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
ce90: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
cea0: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
ceb0: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
cec0: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
ced0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
cee0: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
cef0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
cf00: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
cf10: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
cf20: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
cf30: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
cf40: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
cf50: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
cf60: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
cf70: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
cf80: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
cf90: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
cfa0: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
cfb0: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
cfc0: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
cfd0: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
cfe0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
cff0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
d000: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
d010: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
d020: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
d030: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
d040: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
d050: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
d060: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d070: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
d080: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
d090: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
d0a0: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
d0b0: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
d0c0: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
d0d0: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
d0e0: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
d0f0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
d100: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
d110: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
d120: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
d130: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
d140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d150: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
d160: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
d170: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
d180: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
d190: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
d1a0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
d1b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
d1c0: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
d1d0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
d1e0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
d1f0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
d200: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
d210: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
d220: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
d230: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
d240: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
d250: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
d260: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
d270: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
d280: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
d290: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
d2a0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
d2b0: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
d2c0: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
d2d0: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
d2e0: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
d2f0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
d300: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
d310: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
d320: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
d330: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
d340: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
d350: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
d360: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d370: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
d380: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d390: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
d3a0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d3b0: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
d3c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d3d0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
d3e0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d3f0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
d400: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
d410: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
d420: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d430: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
d440: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
d450: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d460: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
d470: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
d480: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
d490: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
d4a0: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
d4b0: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
d4c0: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
d4d0: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
d4e0: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
d4f0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
d500: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
d510: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
d520: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
d530: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
d540: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
d550: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
d560: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
d570: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
d580: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
d590: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
d5a0: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
d5b0: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
d5c0: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
d5d0: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
d5e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
d5f0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
d600: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
d610: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
d620: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
d630: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
d640: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
d650: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
d660: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
d670: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
d680: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
d690: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
d6a0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
d6b0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
d6c0: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
d6d0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
d6e0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
d6f0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
d700: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
d710: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
d720: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
d730: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
d740: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d750: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
d760: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
d770: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
d780: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
d790: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
d7a0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
d7b0: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
d7c0: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
d7d0: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
d7e0: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
d7f0: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
d800: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
d810: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
d820: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
d830: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
d840: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
d850: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
d860: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
d870: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
d880: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
d890: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
d8a0: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
d8b0: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
d8c0: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
d8d0: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
d8e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
d8f0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
d900: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
d910: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
d920: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
d930: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
d940: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
d950: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
d960: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
d970: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
d980: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
d990: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
d9a0: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
d9b0: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
d9c0: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
d9d0: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
d9e0: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
d9f0: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
da00: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
da10: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
da20: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
da30: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
da40: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
da50: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
da60: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
da70: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
da80: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
da90: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
daa0: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
dab0: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
dac0: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
dad0: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
dae0: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
daf0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
db00: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
db10: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
db20: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
db30: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
db40: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
db50: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
db60: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
db70: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
db80: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
db90: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
dba0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
dbb0: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
dbc0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
dbd0: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
dbe0: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
dbf0: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
dc00: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
dc10: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
dc20: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
dc30: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
dc40: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
dc50: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
dc60: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
dc70: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
dc80: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
dc90: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
dca0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
dcb0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
dcc0: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
dcd0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
dce0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
dcf0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
dd00: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
dd10: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
dd20: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
dd30: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
dd40: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
dd50: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
dd60: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
dd70: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
dd80: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
dd90: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
dda0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
ddb0: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
ddc0: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
ddd0: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
dde0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
ddf0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
de00: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
de10: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
de20: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
de30: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
de40: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
de50: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
de60: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
de70: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
de80: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
de90: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
dea0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
deb0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
dec0: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
ded0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
dee0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
def0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
df00: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
df10: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
df20: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
df30: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
df40: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
df50: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
df60: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
df70: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
df80: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
df90: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
dfa0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
dfb0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
dfc0: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
dfd0: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
dfe0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
dff0: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
e000: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
e010: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
e020: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
e030: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
e040: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
e050: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
e060: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
e070: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
e080: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
e090: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
e0a0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
e0b0: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
e0c0: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
e0d0: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
e0e0: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
e0f0: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
e100: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
e110: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
e120: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
e130: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
e140: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
e150: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
e160: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
e170: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
e180: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
e190: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
e1a0: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
e1b0: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
e1c0: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
e1d0: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
e1e0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
e1f0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
e200: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
e210: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
e220: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
e230: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
e240: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
e250: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
e260: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
e270: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
e280: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
e290: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
e2a0: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
e2b0: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
e2c0: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
e2d0: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
e2e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
e2f0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
e300: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
e310: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
e320: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
e330: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
e340: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
e350: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
e360: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
e370: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
e380: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
e390: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
e3a0: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
e3b0: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
e3c0: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
e3d0: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
e3e0: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
e3f0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
e400: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
e410: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
e420: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
e430: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
e440: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
e450: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
e460: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
e470: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
e480: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
e490: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
e4a0: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
e4b0: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
e4c0: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
e4d0: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
e4e0: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
e4f0: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
e500: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
e510: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
e520: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
e530: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
e540: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
e550: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
e560: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
e570: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
e580: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
e590: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
e5a0: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
e5b0: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
e5c0: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
e5d0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
e5e0: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
e5f0: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
e600: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
e610: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
e620: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
e630: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
e640: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
e650: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
e660: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
e670: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
e680: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
e690: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
e6a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
e6b0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
e6c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
e6d0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
e6e0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
e6f0: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
e700: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
e710: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
e720: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
e730: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
e740: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
e750: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
e760: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
e770: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
e780: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
e790: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
e7a0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
e7b0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
e7c0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
e7d0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
e7e0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
e7f0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
e800: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
e810: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
e820: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
e830: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
e840: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e850: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e860: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
e870: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
e880: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
e890: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
e8a0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
e8b0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e8c0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
e8d0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
e8e0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
e8f0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e900: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
e910: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
e920: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
e930: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
e940: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e950: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e960: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
e970: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
e980: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
e990: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e9a0: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
e9b0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
e9c0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
e9d0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
e9e0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
e9f0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
ea00: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
ea10: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ea20: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
ea30: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
ea40: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
ea50: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
ea60: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
ea70: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
ea80: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
ea90: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
eaa0: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
eab0: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
eac0: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
ead0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
eae0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
eaf0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
eb00: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
eb10: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
eb20: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
eb30: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
eb40: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
eb50: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
eb60: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
eb70: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
eb80: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
eb90: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
eba0: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
ebb0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
ebc0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
ebd0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
ebe0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
ebf0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
ec00: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
ec10: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
ec20: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
ec30: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
ec40: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
ec50: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
ec60: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
ec70: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
ec80: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
ec90: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
eca0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
ecb0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
ecc0: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
ecd0: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
ece0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ecf0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ed00: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
ed10: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
ed20: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ed30: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ed40: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
ed50: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ed60: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ed70: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
ed80: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
ed90: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
eda0: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
edb0: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
edc0: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
edd0: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
ede0: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
edf0: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
ee00: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
ee10: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
ee20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
ee30: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
ee40: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
ee50: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
ee60: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
ee70: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
ee80: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
ee90: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
eea0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
eeb0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
eec0: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
eed0: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
eee0: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
eef0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ef00: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
ef10: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
ef20: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
ef30: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
ef40: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
ef50: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
ef60: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
ef70: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
ef80: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
ef90: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
efa0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
efb0: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
efc0: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
efd0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
efe0: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
eff0: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
f000: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
f010: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
f020: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
f030: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
f040: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
f050: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
f060: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
f070: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
f080: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
f090: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
f0a0: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
f0b0: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
f0c0: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
f0d0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
f0e0: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
f0f0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
f100: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f110: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
f120: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
f130: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
f140: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f150: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
f160: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
f170: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
f180: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
f190: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
f1a0: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
f1b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
f1c0: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
f1d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
f1e0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f1f0: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
f200: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
f210: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
f220: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
f230: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
f240: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
f250: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f260: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
f270: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
f280: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
f290: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
f2a0: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
f2b0: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
f2c0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
f2d0: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
f2e0: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
f2f0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
f300: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
f310: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
f320: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
f330: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
f340: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
f350: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
f360: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
f370: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
f380: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f390: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f3a0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
f3b0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f3c0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f3d0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
f3e0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
f3f0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f400: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
f410: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
f420: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
f430: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
f440: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
f450: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
f460: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
f470: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
f480: 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
f490: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
f4a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
f4b0: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
f4c0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
f4d0: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
f4e0: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
f4f0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
f500: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
f510: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
f520: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
f530: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
f540: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
f550: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
f560: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
f570: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f580: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
f590: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
f5a0: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
f5b0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
f5c0: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
f5d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
f5e0: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
f5f0: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
f600: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
f610: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
f620: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
f630: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
f640: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
f650: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
f660: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
f670: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
f680: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
f690: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
f6a0: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
f6b0: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
f6c0: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
f6d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f6e0: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
f6f0: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
f700: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
f710: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
f720: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
f730: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f740: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
f750: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
f760: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
f770: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
f780: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
f790: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
f7a0: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
f7b0: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
f7c0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
f7d0: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
f7e0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
f7f0: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
f800: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
f810: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
f820: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
f830: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
f840: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
f850: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
f860: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
f870: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
f880: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
f890: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
f8a0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
f8b0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
f8c0: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
f8d0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
f8e0: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
f8f0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
f900: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
f910: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
f920: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
f930: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
f940: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
f950: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
f960: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f970: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
f980: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
f990: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f9a0: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
f9b0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
f9c0: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
f9d0: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
f9e0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
f9f0: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
fa00: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
fa10: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
fa20: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
fa30: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fa40: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
fa50: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
fa60: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
fa70: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
fa80: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
fa90: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
faa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
fab0: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
fac0: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
fad0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fae0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
faf0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
fb00: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
fb10: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
fb20: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
fb30: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
fb40: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
fb50: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fb60: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
fb70: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
fb80: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fb90: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
fba0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
fbb0: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
fbc0: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
fbd0: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
fbe0: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
fbf0: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
fc00: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
fc10: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
fc20: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
fc30: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
fc40: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
fc50: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
fc60: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
fc70: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
fc80: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
fc90: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
fca0: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
fcb0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
fcc0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
fcd0: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
fce0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
fcf0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
fd00: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
fd10: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
fd20: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
fd30: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
fd40: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
fd50: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
fd60: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
fd70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fd80: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
fd90: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
fda0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
fdb0: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
fdc0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
fdd0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
fde0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
fdf0: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
fe00: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
fe10: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
fe20: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
fe30: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fe40: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
fe50: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
fe60: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
fe70: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
fe80: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
fe90: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
fea0: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
feb0: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
fec0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fed0: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
fee0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
fef0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
ff00: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
ff10: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
ff20: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
ff30: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
ff40: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
ff50: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
ff60: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
ff70: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
ff80: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
ff90: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
ffa0: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
ffb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
ffc0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
ffd0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
ffe0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
fff0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
10000 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
10010 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
10020 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
10030 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
10040 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10050 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
10060 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
10070 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
10080 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
10090 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
100a0 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
100b0 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
100c0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
100d0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
100e0 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
100f0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10100 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
10110 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
10120 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
10130 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
10140 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
10150 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
10160 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
10170 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
10180 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
10190 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
101a0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
101b0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
101c0 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
101d0 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
101e0 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
101f0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
10200 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
10210 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
10220 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
10230 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
10240 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
10250 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
10260 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
10270 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
10280 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
10290 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
102a0 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
102b0 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
102c0 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
102d0 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
102e0 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
102f0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
10300 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
10310 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
10320 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
10330 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
10340 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
10350 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
10360 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
10370 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
10380 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
10390 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
103a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
103b0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
103c0 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
103d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
103e0 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
103f0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
10400 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
10410 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
10420 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
10430 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
10440 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
10450 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10460 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
10470 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
10480 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
10490 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
104a0 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
104b0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
104c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
104d0 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
104e0 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
104f0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
10500 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
10510 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
10520 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
10530 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10540 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
10550 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
10560 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
10570 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
10580 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
10590 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
105a0 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
105b0 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
105c0 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
105d0 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
105e0 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
105f0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
10600 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
10610 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
10620 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
10630 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
10640 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
10650 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
10660 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10670 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
10680 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
10690 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
106a0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
106b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
106c0 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
106d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
106e0 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
106f0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
10700 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
10710 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
10720 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10730 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
10740 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
10750 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
10760 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
10770 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
10780 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
10790 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
107a0 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
107b0 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
107c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
107d0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
107e0 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
107f0 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
10800 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
10810 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
10820 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
10830 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
10840 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
10850 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
10860 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
10870 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
10880 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
10890 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
108a0 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
108b0 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
108c0 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
108d0 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
108e0 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
108f0 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
10900 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
10910 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65  ds..**.** <b>The
10920 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10930 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
10940 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54  ot threadsafe. T
10950 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
10960 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68  * must ensure th
10970 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
10980 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
10990 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
109a0 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
109b0 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
109c0 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
109d0 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  </b>.**.** The s
109e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
109f0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79  interface.** may
10a00 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
10a10 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
10a20 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
10a30 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
10a40 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
10a50 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
10a60 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
10a70 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
10a80 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
10a90 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
10aa0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
10ab0 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
10ac0 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
10ad0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
10ae0 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
10af0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
10b00 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
10b10 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
10b20 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
10b30 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
10b40 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
10b50 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
10b60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
10b70 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
10b80 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
10b90 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10ba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
10bb0 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
10bc0 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
10bd0 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
10be0 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
10bf0 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
10c00 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
10c10 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
10c20 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
10c30 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
10c40 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
10c50 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10c60 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
10c70 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
10c80 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
10c90 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10ca0 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
10cb0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
10cc0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
10cd0 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
10ce0 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
10cf0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
10d00 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
10d10 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
10d20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
10d30 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
10d40 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  code]..*/.int sq
10d50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
10d60 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
10d70 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
10d80 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
10d90 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  ections.** METHO
10da0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
10db0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
10dc0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
10dd0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
10de0 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
10df0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
10e00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10e10 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
10e20 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
10e30 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
10e40 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
10e50 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
10e60 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
10e70 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
10e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
10e90 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
10ea0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
10eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
10ec0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
10ed0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10ee0 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
10ef0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  .** [SQLITE_DBCO
10f00 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c  NFIG_LOOKASIDE |
10f10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
10f20 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65  erb] - an intege
10f30 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20  r code .** that 
10f40 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61  indicates what a
10f50 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
10f60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10f70 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
10f80 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65  igured..** Subse
10f90 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20  quent arguments 
10fa0 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
10fb0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
10fc0 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  ion verb..**.** 
10fd0 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
10fe0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
10ff0 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
11000 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
11010 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
11020 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
11030 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
11040 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
11050 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
11060 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
11070 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
11080 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
11090 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
110a0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
110b0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
110c0 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
110d0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
110e0 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
110f0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
11100 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
11110 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
11120 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
11130 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
11140 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
11150 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
11160 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
11170 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
11180 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
11190 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
111a0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
111b0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
111c0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
111d0 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
111e0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
111f0 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
11200 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
11210 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
11220 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
11230 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
11240 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
11250 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
11260 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
11270 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
11280 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
11290 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
112a0 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
112b0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
112c0 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
112d0 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
112e0 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
112f0 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
11300 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
11310 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
11320 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
11330 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11340 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
11350 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
11360 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
11370 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
11380 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
11390 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
113a0 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
113b0 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
113c0 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
113d0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
113e0 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
113f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11400 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
11410 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
11420 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
11430 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
11440 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
11450 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
11460 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
11470 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
11480 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
11490 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
114a0 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
114b0 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
114c0 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
114d0 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
114e0 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
114f0 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
11500 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
11510 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
11520 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
11530 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
11540 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
11550 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
11560 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
11570 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
11580 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
11590 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
115a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
115b0 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
115c0 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
115d0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
115e0 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
115f0 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
11600 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
11610 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
11620 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
11630 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
11640 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
11650 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
11660 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
11670 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
11680 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
11690 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
116a0 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
116b0 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
116c0 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
116d0 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
116e0 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
116f0 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
11700 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
11710 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
11720 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
11730 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
11740 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
11750 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
11760 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
11770 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
11780 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
11790 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
117a0 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
117b0 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
117c0 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
117d0 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
117e0 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
117f0 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
11800 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
11810 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
11820 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
11830 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
11840 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
11850 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
11860 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
11870 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
11880 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
11890 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
118a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
118b0 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
118c0 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
118d0 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
118e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
118f0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a   For example,.**
11900 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
11910 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
11920 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
11930 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
11940 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
11950 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
11960 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
11970 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
11980 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
11990 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
119a0 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
119b0 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
119c0 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
119d0 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
119e0 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
119f0 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
11a00 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
11a10 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
11a20 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
11a30 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
11a40 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
11a50 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
11a60 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
11a70 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
11a80 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
11a90 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
11aa0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
11ab0 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
11ac0 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
11ad0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
11ae0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11af0 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
11b00 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
11b10 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
11b20 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
11b30 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
11b40 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
11b50 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
11b60 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
11b70 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
11b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11b90 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
11ba0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
11bb0 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
11bc0 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
11bd0 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
11be0 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
11bf0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
11c00 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
11c10 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
11c20 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11c30 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
11c40 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
11c50 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
11c60 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
11c70 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
11c80 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
11c90 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
11ca0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
11cb0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
11cc0 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
11cd0 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
11ce0 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
11cf0 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
11d00 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
11d10 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
11d20 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
11d30 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
11d40 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
11d50 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
11d60 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
11d70 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
11d80 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
11d90 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
11da0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
11db0 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
11dc0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
11dd0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
11de0 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
11df0 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
11e00 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
11e10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
11e20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
11e30 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
11e40 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
11e50 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
11e60 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
11e70 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
11e80 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
11e90 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
11ea0 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
11eb0 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
11ec0 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
11ed0 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
11ee0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
11ef0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
11f00 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
11f10 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
11f20 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
11f30 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11f40 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
11f50 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
11f60 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
11f70 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
11f80 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
11f90 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
11fa0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
11fb0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
11fc0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
11fd0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
11fe0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
11ff0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
12000 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
12010 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12020 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
12030 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
12040 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12050 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
12060 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
12070 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
12080 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12090 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
120a0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
120b0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
120c0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
120d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
120e0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
120f0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
12100 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
12110 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
12120 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
12130 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12140 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
12150 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
12160 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
12170 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
12180 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
12190 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
121a0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
121b0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
121c0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
121d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
121e0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
121f0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
12200 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12210 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
12220 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12230 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
12240 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
12250 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
12260 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12270 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
12280 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
12290 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
122a0 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
122b0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
122c0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
122d0 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
122e0 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
122f0 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
12300 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
12310 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
12320 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
12330 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12340 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12350 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12360 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12370 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12380 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12390 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
123a0 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
123b0 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
123c0 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
123d0 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
123e0 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
123f0 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
12400 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
12410 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
12420 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12430 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
12440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
12450 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
12460 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12470 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
12480 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
12490 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
124a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
124b0 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
124c0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
124d0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
124e0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
124f0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
12500 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
12510 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
12520 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
12530 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
12540 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
12550 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
12560 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
12570 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12580 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
12590 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
125a0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
125b0 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
125c0 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
125d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
125e0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
125f0 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
12600 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
12610 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
12620 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
12630 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
12640 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
12650 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
12660 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
12670 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
12680 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
12690 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
126a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
126b0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
126c0 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
126d0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
126e0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
126f0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
12700 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
12710 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12720 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
12730 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
12740 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
12750 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
12760 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
12770 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12780 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
12790 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
127a0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
127b0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
127c0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
127d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
127e0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
127f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
12800 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
12810 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
12820 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
12830 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12840 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
12850 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
12860 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
12870 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
12880 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
12890 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
128a0 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
128b0 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
128c0 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
128d0 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
128e0 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
128f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12900 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
12910 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
12920 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
12930 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
12940 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
12950 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
12960 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
12970 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
12980 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
12990 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
129a0 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
129b0 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
129c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
129d0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
129e0 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
129f0 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
12a00 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
12a10 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
12a20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12a30 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
12a40 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
12a50 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
12a60 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
12a70 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
12a80 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
12a90 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12aa0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
12ab0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
12ac0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
12ad0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
12ae0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
12af0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
12b00 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
12b10 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
12b20 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
12b30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12b40 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
12b50 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
12b60 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
12b70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
12b80 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
12b90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
12ba0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12bb0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12bc0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12bd0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
12be0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
12bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12c00 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
12c10 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
12c20 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
12c30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
12c40 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
12c50 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
12c60 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
12c70 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
12c80 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
12c90 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
12ca0 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
12cb0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
12cc0 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
12cd0 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
12ce0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12cf0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
12d00 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
12d10 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
12d20 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
12d30 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
12d40 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
12d50 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12d60 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
12d70 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
12d80 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
12d90 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
12da0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12db0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
12dc0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12dd0 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
12de0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
12df0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12e00 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
12e10 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12e20 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
12e30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12e40 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12e50 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12e60 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12e70 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
12e80 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
12e90 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
12ea0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
12eb0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
12ec0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12ed0 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
12ee0 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
12ef0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
12f00 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
12f10 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
12f20 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
12f30 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
12f40 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
12f50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12f60 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
12f70 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
12f80 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
12f90 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
12fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12fb0 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
12fc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12fd0 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
12fe0 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
12ff0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
13000 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
13010 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
13020 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74  type int,.** int
13030 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
13040 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
13050 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
13060 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
13070 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  of.** memory all
13080 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
13090 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
130a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
130b0 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64  tistics are.** d
130c0 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
130d0 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
130e0 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
130f0 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
13100 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
13110 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
13120 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
13130 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
13140 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
13150 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
13160 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
13170 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
13180 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
13190 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20  tatus64()].**   
131a0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
131b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
131c0 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
131d0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
131e0 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
131f0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
13200 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
13210 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
13220 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
13230 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
13240 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
13250 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
13260 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
13270 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13280 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
13290 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
132a0 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
132b0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
132c0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
132d0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
132e0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
132f0 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  y buffer.** that
13300 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
13310 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  for scratch memo
13320 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65  ry.  ^(There are
13330 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
13340 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  .** to SQLITE_CO
13350 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41  NFIG_SCRATCH:  A
13360 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
13370 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
13380 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
13390 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
133a0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
133b0 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
133c0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
133d0 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
133e0 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
133f0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
13400 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
13410 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
13420 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  )^.** The first 
13430 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
13440 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13450 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13460 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
13470 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
13480 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
13490 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20  SQLite will not 
134a0 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  use more than on
134b0 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  e scratch buffer
134c0 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a  s per thread..**
134d0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
134e0 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63  ver request a sc
134f0 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
13500 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
13510 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
13520 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
13530 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
13540 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
13550 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
13560 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
13570 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
13580 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
13590 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
135a0 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
135b0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
135c0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
135d0 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
135e0 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e  ded.<p>.** ^When
135f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13600 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d   provides any am
13610 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20  ount of scratch 
13620 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20  memory using.** 
13630 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13640 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76  RATCH, SQLite av
13650 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79  oids unnecessary
13660 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74   large.** [sqlit
13670 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61  e3_malloc|heap a
13680 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20  llocations]..** 
13690 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52  This can help [R
136a0 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76  obson proof|prev
136b0 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ent memory alloc
136c0 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20  ation failures] 
136d0 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66  due to heap.** f
136e0 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20  ragmentation in 
136f0 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64  low-memory embed
13700 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20  ded systems..** 
13710 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13720 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
13730 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
13740 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13750 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
13760 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
13770 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
13780 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
13790 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20   memory pool.** 
137a0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
137b0 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
137c0 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
137d0 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
137e0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
137f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
13800 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
13810 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
13820 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61   a no-op if an a
13830 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
13840 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
13850 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
13860 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
13870 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
13880 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e  G_PCACHE2]..** ^
13890 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
138a0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
138b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
138c0 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
138d0 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
138e0 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65  gned memory (pMe
138f0 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  m), the size of 
13900 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20  each page cache 
13910 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  line (sz),.** an
13920 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
13930 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e  cache lines (N).
13940 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
13950 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
13960 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
13970 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
13980 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
13990 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
139a0 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
139b0 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
139c0 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
139d0 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
139e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
139f0 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
13a00 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
13a10 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
13a20 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53  ermined using [S
13a30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13a40 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e  CHE_HDRSZ]..** ^
13a50 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
13a60 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
13a70 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
13a80 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
13a90 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
13aa0 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
13ab0 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20  y.  The pMem.** 
13ac0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
13ad0 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
13ae0 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e  ointer or a poin
13af0 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
13b00 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  .** aligned bloc
13b10 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61  k of memory of a
13b20 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
13b30 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  es, otherwise.**
13b40 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
13b50 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
13b60 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d  d..** ^When pMem
13b70 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
13b80 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65  Lite will strive
13b90 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f   to use the memo
13ba0 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74  ry provided.** t
13bb0 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63  o satisfy page c
13bc0 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c  ache needs, fall
13bd0 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c  ing back to [sql
13be0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
13bf0 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68  f.** a page cach
13c00 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72  e line is larger
13c10 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f   than sz bytes o
13c20 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20  r if all of the 
13c30 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69  pMem buffer.** i
13c40 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
13c50 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c  ^If pMem is NULL
13c60 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65   and N is non-ze
13c70 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61  ro, then each da
13c80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13c90 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69  n.** does an ini
13ca0 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61  tial bulk alloca
13cb0 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61  tion for page ca
13cc0 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72  che memory.** fr
13cd0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
13ce0 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74  oc()] sufficient
13cf0 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e   for N cache lin
13d00 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  es if N is posit
13d10 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30  ive or.** of -10
13d20 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20  24*N bytes if N 
13d30 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e  is negative, . ^
13d40 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
13d50 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
13d60 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
13d70 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
13d80 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74  ided by the init
13d90 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ial.** allocatio
13da0 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67  n, then SQLite g
13db0 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
13dc0 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61  malloc()] separa
13dd0 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a  tely for each.**
13de0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68   additional cach
13df0 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  e line. </dd>.**
13e00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13e10 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
13e20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13e30 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
13e40 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13e50 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
13e60 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
13e70 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
13e80 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
13e90 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
13ea0 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
13eb0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13ec0 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
13ed0 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
13ee0 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
13ef0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
13f00 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  nd.** [SQLITE_CO
13f10 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
13f20 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
13f30 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
13f40 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
13f50 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
13f60 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
13f70 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  th either [SQLIT
13f80 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
13f90 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ] or [SQLITE_ENA
13fa0 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64  BLE_MEMSYS5] and
13fb0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
13fc0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e  ITE_ERROR] if in
13fd0 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e  voked otherwise.
13fe0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
13ff0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
14000 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
14010 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79  HEAP:.** An 8-by
14020 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
14030 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
14040 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
14050 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
14060 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
14070 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
14080 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
14090 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
140a0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
140b0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
140c0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
140d0 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
140e0 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
140f0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
14100 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
14110 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
14120 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
14130 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
14140 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
14150 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
14160 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
14170 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
14180 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
14190 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
141a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
141b0 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
141c0 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
141d0 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
141e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
141f0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
14200 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
14210 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
14220 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
14230 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
14240 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
14250 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
14260 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
14270 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
14280 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
14290 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
142a0 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
142b0 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
142c0 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
142d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
142e0 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
142f0 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
14300 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14310 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
14320 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
14330 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
14340 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14350 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e  FIG_MUTEX option
14360 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14370 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
14380 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
14390 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
143a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
143b0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
143c0 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
143d0 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
143e0 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  s alternative lo
143f0 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
14400 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
14410 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68  d.** in place th
14420 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
14430 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
14440 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
14450 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  akes a copy of.*
14460 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
14470 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
14480 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
14490 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
144a0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
144b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
144c0 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
144d0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
144e0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
144f0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
14500 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
14510 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
14520 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
14530 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
14540 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
14550 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
14560 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
14570 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
14580 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14590 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
145a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
145b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
145c0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
145d0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
145e0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
145f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
14600 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
14610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14620 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
14630 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14640 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f  ONFIG_GETMUTEX o
14650 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14660 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14670 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
14680 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
14690 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
146a0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
146b0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
146c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
146d0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
146e0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
146f0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
14700 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
14710 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
14720 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
14730 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
14740 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
14750 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
14760 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
14770 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
14780 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
14790 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
147a0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
147b0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
147c0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
147d0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
147e0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
147f0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
14800 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
14810 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14820 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14830 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
14840 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
14850 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
14860 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
14870 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
14880 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
14890 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
148a0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
148b0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
148c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
148d0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
148e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
148f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14900 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14910 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
14920 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14930 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
14940 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14950 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70  FIG_LOOKASIDE op
14960 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
14970 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
14980 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64  termine.** the d
14990 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c  efault size of l
149a0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
149b0 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73  on each [databas
149c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
149d0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
149e0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
149f0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
14a00 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
14a10 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
14a20 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
14a30 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
14a40 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
14a50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14a60 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f  .)^  ^(SQLITE_CO
14a70 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a  NFIG_LOOKASIDE.*
14a80 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65  * sets the <i>de
14a90 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
14aa0 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
14ab0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
14ac0 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74  OOKASIDE].** opt
14ad0 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ion to [sqlite3_
14ae0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
14af0 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
14b00 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
14b10 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
14b20 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
14b30 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
14b40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14b50 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
14b60 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
14b70 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
14b80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14b90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14ba0 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
14bb0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14bc0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
14bd0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
14be0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
14bf0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
14c00 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
14c10 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ct specifies.** 
14c20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  the interface to
14c30 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
14c40 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
14c50 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74  ion.)^.** ^SQLit
14c60 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
14c70 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  f the [sqlite3_p
14c80 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
14c90 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
14ca0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14cb0 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
14cc0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14cd0 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
14ce0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14d00 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  TPCACHE2 option 
14d10 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14d20 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
14d30 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
14d40 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
14d50 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
14d60 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
14d70 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63  pies of.** the c
14d80 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68  urrent page cach
14d90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14da0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
14db0 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
14dc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14dd0 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
14de0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
14df0 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
14e00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
14e10 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
14e20 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
14e30 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
14e40 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
14e50 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
14e60 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
14e70 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
14e80 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
14e90 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
14ea0 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
14eb0 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
14ec0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
14ed0 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
14ee0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
14ef0 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
14f00 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
14f10 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
14f20 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
14f30 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
14f40 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
14f50 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
14f60 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
14f70 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
14f80 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
14f90 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
14fa0 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
14fb0 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
14fc0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
14fd0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14fe0 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
14ff0 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
15000 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
15010 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
15020 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
15030 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
15040 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
15050 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
15060 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
15070 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
15080 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
15090 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
150a0 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
150b0 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
150c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
150d0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
150e0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
150f0 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
15100 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
15110 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
15120 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
15130 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
15140 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15150 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
15160 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
15170 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
15180 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
15190 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
151a0 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
151b0 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
151c0 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
151d0 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
151e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
151f0 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
15200 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
15210 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
15220 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
15230 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
15240 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
15250 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
15260 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
15270 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
15280 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
15290 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
152a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
152b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
152c0 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
152d0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
152e0 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74  FIG_URI option t
152f0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
15300 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
15310 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65  nt..** If non-ze
15320 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
15330 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
15340 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
15350 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
15360 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49  ero,.** then URI
15370 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
15380 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29  bally disabled.)
15390 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69  ^ ^If URI handli
153a0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
153b0 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  * enabled, all f
153c0 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20  ilenames passed 
153d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
153e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
153f0 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  en_v2()],.** [sq
15400 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
15410 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
15420 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
15430 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
15440 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
15450 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
15460 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
15470 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
15480 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
15490 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
154a0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
154b0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
154c0 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
154d0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
154e0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
154f0 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
15500 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
15510 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
15520 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
15530 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
15540 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
15550 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
15560 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
15570 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
15580 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
15590 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
155a0 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
155b0 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
155c0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
155d0 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
155e0 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
155f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
15600 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
15610 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
15620 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
15630 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
15640 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
15650 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
15660 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20  DEX_SCAN option 
15670 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
15680 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65  nteger.** argume
15690 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
156a0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
156b0 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
156c0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
156d0 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  le.** the use of
156e0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
156f0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
15700 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
15710 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a  ery optimizer..*
15720 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
15730 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
15740 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
15750 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
15760 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15770 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
15780 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
15790 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
157a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
157b0 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
157c0 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
157d0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
157e0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
157f0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
15800 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
15810 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
15820 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
15830 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
15840 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
15850 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f  on.** when the o
15860 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
15870 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
15880 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
15890 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
158a0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
158b0 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
158c0 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
158d0 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
158e0 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
158f0 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
15900 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
15910 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
15920 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15930 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
15940 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
15950 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
15960 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
15970 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15980 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
15990 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
159a0 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
159b0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
159c0 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
159d0 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
159e0 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
159f0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
15a00 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
15a10 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ps..** </dd>.**.
15a20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15a30 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
15a40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15a50 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
15a60 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
15a70 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
15a80 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
15a90 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
15aa0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
15ab0 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOG] pre-proces
15ac0 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
15ad0 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
15ae0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
15af0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
15b00 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
15b10 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
15b20 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
15b30 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
15b40 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
15b50 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
15b60 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
15b70 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
15b80 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
15b90 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
15ba0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
15bb0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
15bc0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
15bd0 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
15be0 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
15bf0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
15c00 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
15c10 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
15c20 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
15c30 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
15c40 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
15c50 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
15c60 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
15c70 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
15c80 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
15c90 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
15ca0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
15cb0 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
15cc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15cd0 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
15ce0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
15cf0 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
15d00 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
15d10 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
15d20 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
15d30 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
15d40 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
15d50 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
15d60 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
15d70 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
15d80 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
15d90 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
15da0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
15db0 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
15dc0 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20   In this case.  
15dd0 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73  An example of us
15de0 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66  ing this.** conf
15df0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15e00 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20   can be seen in 
15e10 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67  the "test_sqllog
15e20 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20  .c" source file 
15e30 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69  in.** the canoni
15e40 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  cal SQLite sourc
15e50 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e tree.</dd>.**.
15e60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15e70 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  IG_MMAP_SIZE]].*
15e80 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15e90 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a  FIG_MMAP_SIZE.**
15ea0 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e   <dd>^SQLITE_CON
15eb0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61  FIG_MMAP_SIZE ta
15ec0 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69  kes two 64-bit i
15ed0 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f  nteger (sqlite3_
15ee0 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a  int64) values.**
15ef0 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65   that are the de
15f00 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20  fault mmap size 
15f10 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75  limit (the defau
15f20 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a  lt setting for.*
15f30 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  * [PRAGMA mmap_s
15f40 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61  ize]) and the ma
15f50 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
15f60 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a  ap size limit..*
15f70 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
15f80 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76  etting can be ov
15f90 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68  erridden by each
15fa0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15fb0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69  tion using.** ei
15fc0 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41  ther the [PRAGMA
15fd0 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d   mmap_size] comm
15fe0 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67  and, or by using
15ff0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
16000 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
16010 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20   file control.  
16020 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  ^(The maximum al
16030 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
16040 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e  ** will be silen
16050 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66  tly truncated if
16060 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68   necessary so th
16070 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  at it does not e
16080 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  xceed the.** com
16090 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75  pile-time maximu
160a0 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20  m mmap size set 
160b0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
160c0 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d  E_MAX_MMAP_SIZE]
160d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
160e0 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65  tion.)^.** ^If e
160f0 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74  ither argument t
16100 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
16110 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
16120 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73  that argument is
16130 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69  .** changed to i
16140 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
16150 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b  default..**.** [
16160 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  [SQLITE_CONFIG_W
16170 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a  IN32_HEAPSIZE]].
16180 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16190 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
161a0 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  IZE.** <dd>^The 
161b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
161c0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74  N32_HEAPSIZE opt
161d0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
161e0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
161f0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66  is.** compiled f
16200 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20  or Windows with 
16210 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
16220 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
16230 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a  ocessor macro.**
16240 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54   defined. ^SQLIT
16250 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16260 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
16270 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
16280 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
16290 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
162a0 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
162b0 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
162c0 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  heap..**.** [[SQ
162d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
162e0 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64  HE_HDRSZ]].** <d
162f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16300 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20  PCACHE_HDRSZ.** 
16310 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
16320 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
16330 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  RSZ option takes
16340 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
16350 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
16360 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
16370 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74  integer and writ
16380 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  es into that int
16390 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20  eger the number 
163a0 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65  of extra.** byte
163b0 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69  s per page requi
163c0 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67  red for each pag
163d0 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e in [SQLITE_CON
163e0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
163f0 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ** The amount of
16400 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71   extra space req
16410 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65  uired can change
16420 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
16430 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74  e compiler,.** t
16440 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20  arget platform, 
16450 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
16460 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
16470 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d  TE_CONFIG_PMASZ]
16480 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
16490 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20  CONFIG_PMASZ.** 
164a0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
164b0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74  CONFIG_PMASZ opt
164c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
164d0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
164e0 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69  ch.** is an unsi
164f0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
16500 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d   sets the "Minim
16510 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72  um PMA Size" for
16520 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64   the multithread
16530 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20  ed.** sorter to 
16540 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54  that integer.  T
16550 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d  he default minim
16560 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73  um PMA Size is s
16570 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
16580 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53  LITE_SORTER_PMAS
16590 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  Z] compile-time 
165a0 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72  option.  New thr
165b0 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65  eads are launche
165c0 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74  d.** to help wit
165d0 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e  h sort operation
165e0 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65  s when multithre
165f0 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20  aded sorting.** 
16600 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e  is enabled (usin
16610 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68  g the [PRAGMA th
16620 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20  reads] command) 
16630 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  and the amount o
16640 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20  f content.** to 
16650 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64  be sorted exceed
16660 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20  s the page size 
16670 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75  times the minimu
16680 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41  m of the.** [PRA
16690 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20  GMA cache_size] 
166a0 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73  setting and this
166b0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   value..**.** [[
166c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
166d0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a  MTJRNL_SPILL]].*
166e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
166f0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
16700 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  LL.** <dd>^The S
16710 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16720 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69  TJRNL_SPILL opti
16730 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16740 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
16750 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65  h.** becomes the
16760 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [statement jour
16770 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69  nal] spill-to-di
16780 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a  sk threshold.  .
16790 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f  ** [Statement jo
167a0 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64  urnals] are held
167b0 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c   in memory until
167c0 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20   their size (in 
167d0 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64  bytes).** exceed
167e0 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64  s this threshold
167f0 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74  , at which point
16800 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65   they are writte
16810 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72  n to disk..** Or
16820 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c   if the threshol
16830 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65  d is -1, stateme
16840 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20  nt journals are 
16850 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65  always held.** e
16860 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65  xclusively in me
16870 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d  mory..** Since m
16880 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  any statement jo
16890 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63  urnals never bec
168a0 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69  ome large, setti
168b0 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20  ng the spill.** 
168c0 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76  threshold to a v
168d0 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b  alue such as 64K
168e0 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72  iB can greatly r
168f0 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74  educe the amount
16900 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69   of.** I/O requi
16910 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73  red to support s
16920 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63  tatement rollbac
16930 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  k..** The defaul
16940 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73  t value for this
16950 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74   setting is cont
16960 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  rolled by the.**
16970 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e   [SQLITE_STMTJRN
16980 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65  L_SPILL] compile
16990 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
169a0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
169b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
169c0 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
169d0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
169e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
169f0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
16a00 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16a10 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16a20 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
16a30 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
16a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16a50 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
16a60 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
16a70 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
16a80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16a90 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
16aa0 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
16ab0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
16ac0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ad0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
16ae0 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
16af0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
16b00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16b10 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
16b20 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
16b30 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
16b40 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
16b50 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
16b60 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
16b70 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
16b80 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
16b90 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16ba0 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
16bb0 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
16bc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16bd0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
16be0 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
16bf0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
16c00 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16c10 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
16c20 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
16c30 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
16c40 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
16c50 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
16c60 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
16c70 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
16c80 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
16c90 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16ca0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
16cb0 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
16cc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16cd0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
16ce0 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
16cf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16d00 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
16d10 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
16d20 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
16d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
16d40 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
16d50 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
16d60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16d70 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
16d80 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
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 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
16db0 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
16dc0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
16dd0 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
16de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16df0 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
16e00 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
16e10 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
16e20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16e30 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
16e40 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
16e50 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
16e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
16e70 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
16e80 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
16e90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16ea0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
16eb0 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
16ec0 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
16ed0 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
16ee0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16ef0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
16f00 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
16f10 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e   nByte */.#defin
16f20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16f30 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20  PCACHE_HDRSZ    
16f40 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a      24  /* int *
16f50 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  psz */.#define S
16f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
16f70 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  SZ              
16f80 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64   25  /* unsigned
16f90 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64   int szPma */.#d
16fa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16fb0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
16fc0 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69  LL      26  /* i
16fd0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a  nt nByte */../*.
16fe0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
16ff0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
17000 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
17010 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
17020 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
17030 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
17040 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
17050 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
17060 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
17070 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
17080 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
17090 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
170a0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
170b0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
170c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
170d0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
170e0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
170f0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
17100 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
17110 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
17120 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
17130 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
17140 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
17150 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
17160 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
17170 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
17180 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
17190 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
171a0 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
171b0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
171c0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
171d0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
171e0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
171f0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
17200 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
17210 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
17220 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
17230 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
17240 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
17250 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
17260 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
17270 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
17280 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
17290 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
172a0 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
172b0 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
172c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
172d0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
172e0 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
172f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
17300 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
17310 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
17320 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
17330 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17340 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
17350 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
17360 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
17370 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
17380 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
17390 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
173a0 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
173b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
173c0 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
173d0 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
173e0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
173f0 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
17400 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
17410 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
17420 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
17430 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
17440 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
17450 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
17460 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
17470 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
17480 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
17490 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
174a0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
174b0 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
174c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
174d0 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
174e0 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
174f0 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
17500 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
17510 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
17520 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
17530 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
17540 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
17550 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
17560 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
17570 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
17580 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17590 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
175a0 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
175b0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
175c0 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
175d0 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
175e0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
175f0 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
17600 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
17610 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
17620 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17630 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
17640 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
17650 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
17660 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
17670 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
17680 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
17690 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
176a0 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
176b0 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
176c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
176d0 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
176e0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
176f0 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
17700 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
17710 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
17720 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
17730 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
17740 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
17750 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
17760 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
17770 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
17780 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
17790 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
177a0 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  .)^</dd>.**.** <
177b0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
177c0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
177d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
177e0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
177f0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17800 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
17810 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
17820 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
17830 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
17840 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
17850 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17860 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
17870 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
17880 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
17890 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
178a0 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
178b0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
178c0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
178d0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
178e0 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
178f0 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
17900 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
17910 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
17920 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
17930 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
17940 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
17950 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
17960 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
17970 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
17980 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
17990 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
179a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
179b0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
179c0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
179d0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
179e0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
179f0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
17a00 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
17a10 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
17a20 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17a30 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
17a40 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17a50 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
17a60 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
17a70 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
17a80 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
17a90 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17aa0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17ab0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17ac0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17ad0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
17ae0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
17af0 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
17b00 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
17b10 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
17b20 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
17b30 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
17b40 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
17b50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17b60 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
17b70 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
17b80 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
17b90 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
17ba0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
17bb0 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
17bc0 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
17bd0 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
17be0 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
17bf0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17c00 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
17c10 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
17c20 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
17c30 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
17c40 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
17c50 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
17c60 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
17c70 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f  G_ENABLE_FTS3_TO
17c80 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20  KENIZER</dt>.** 
17c90 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17ca0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17cb0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
17cc0 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a  he two-argument.
17cd0 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ** version of th
17ce0 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  e [fts3_tokenize
17cf0 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68  r()] function wh
17d00 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74  ich is part of t
17d10 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c  he.** [FTS3] ful
17d20 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e  l-text search en
17d30 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a  gine extension..
17d40 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
17d50 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
17d60 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
17d70 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
17d80 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
17d90 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
17da0 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65  isable fts3_toke
17db0 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f  nizer() or.** po
17dc0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
17dd0 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28   fts3_tokenizer(
17de0 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  ) or negative to
17df0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
17e00 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  ng.** unchanged.
17e10 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
17e20 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
17e30 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
17e40 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
17e50 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
17e60 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
17e70 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b  whether fts3_tok
17e80 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  enizer is disabl
17e90 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
17ea0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
17eb0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
17ec0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
17ed0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
17ee0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
17ef0 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
17f00 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17f10 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17f20 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17f30 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17f40 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c  _LOAD_EXTENSION<
17f50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17f60 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
17f70 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
17f80 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69  isable the [sqli
17f90 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
17fa0 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  on()].** interfa
17fb0 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79  ce independently
17fc0 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78   of the [load_ex
17fd0 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66  tension()] SQL f
17fe0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
17ff0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
18000 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
18010 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72  ] API enables or
18020 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74   disables both t
18030 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c  he.** C-API [sql
18040 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
18050 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53  ion()] and the S
18060 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61  QL function [loa
18070 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a  d_extension()]..
18080 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
18090 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
180a0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
180b0 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61  When the first a
180c0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
180d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20  interface is 1, 
180e0 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d  then only the C-
180f0 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65  API is.** enable
18100 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  d and the SQL fu
18110 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64  nction remains d
18120 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65  isabled.  If the
18130 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18140 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72  to.** this inter
18150 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20  face is 0, then 
18160 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61  both the C-API a
18170 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
18180 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64  ion are disabled
18190 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73  ..** If the firs
181a0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31  t argument is -1
181b0 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65  , then no change
181c0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74  s are made to st
181d0 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68  ate of either th
181e0 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68  e.** C-API or th
181f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  e SQL function..
18200 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
18210 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
18220 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
18230 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
18240 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
18250 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
18260 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  hether [sqlite3_
18270 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
18280 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
18290 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
182a0 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  abled following 
182b0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
182c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
182d0 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c   may.** be a NUL
182e0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68  L pointer, in wh
182f0 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
18300 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
18310 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a  reported back..*
18320 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
18330 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18340 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74  G_MAINDBNAME</dt
18350 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
18360 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
18370 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d  o change the nam
18380 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20  e of the "main" 
18390 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65  database.** sche
183a0 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61  ma.  ^The sole a
183b0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
183c0 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61  nter to a consta
183d0 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a  nt UTF8 string.*
183e0 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63  * which will bec
183f0 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65  ome the new sche
18400 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65  ma name in place
18410 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51   of "main".  ^SQ
18420 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  Lite.** does not
18430 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
18440 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68  the new main sch
18450 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c  ema name string,
18460 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   so the applicat
18470 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
18480 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75  re that the argu
18490 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f  ment passed into
184a0 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f   this DBCONFIG o
184b0 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67  ption is unchang
184c0 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65  ed.** until afte
184d0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
184e0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
184f0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
18500 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
18510 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18520 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20  G_MAINDBNAME    
18530 20 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20          1000 /* 
18540 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23  const char* */.#
18550 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
18560 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
18570 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30               100
18580 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69  1 /* void* int i
18590 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
185a0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
185b0 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20  ABLE_FKEY       
185c0 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20      1002 /* int 
185d0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
185e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
185f0 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
18600 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e        1003 /* in
18610 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
18620 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18630 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f  G_ENABLE_FTS3_TO
18640 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20  KENIZER 1004 /* 
18650 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
18660 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18670 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f  FIG_ENABLE_LOAD_
18680 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f  EXTENSION 1005 /
18690 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
186a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
186b0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
186c0 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
186d0 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f  t Codes.** METHO
186e0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
186f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
18700 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
18710 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
18720 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
18730 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
18740 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
18750 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
18760 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
18770 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
18780 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
18790 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
187a0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
187b0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
187c0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
187d0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
187e0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
187f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18800 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
18810 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Rowid.** METHOD:
18820 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
18830 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
18840 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
18850 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
18860 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
18870 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
18880 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
18890 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
188a0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
188b0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
188c0 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
188d0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
188e0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
188f0 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
18900 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
18910 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
18920 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
18930 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
18940 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
18950 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
18960 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
18970 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
18980 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
18990 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
189a0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
189b0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
189c0 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
189d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
189e0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
189f0 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
18a00 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
18a10 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
18a20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
18a30 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
18a40 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
18a50 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
18a60 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
18a70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18a80 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72  ion D..** ^Inser
18a90 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
18aa0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
18ab0 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e  re not recorded.
18ac0 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
18ad0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
18ae0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
18af0 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
18b00 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64  ccurred on the d
18b10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18b20 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73  on D, .** then s
18b30 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
18b40 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
18b50 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
18b60 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
18b70 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
18b80 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
18b90 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
18ba0 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
18bb0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
18bc0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
18bd0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
18be0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
18bf0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
18c00 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
18c10 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
18c20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
18c30 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
18c40 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
18c50 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
18c60 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
18c70 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
18c80 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
18c90 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
18ca0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
18cb0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
18cc0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
18cd0 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
18ce0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
18cf0 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
18d00 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
18d10 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
18d20 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
18d30 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
18d40 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
18d50 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
18d60 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
18d70 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
18d80 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
18d90 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
18da0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
18db0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
18dc0 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
18dd0 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
18de0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
18df0 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
18e00 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
18e10 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
18e20 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
18e30 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
18e40 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
18e50 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
18e60 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
18e70 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
18e80 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
18e90 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
18ea0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
18eb0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
18ec0 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
18ed0 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
18ee0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
18ef0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
18f00 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
18f10 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
18f20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
18f30 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
18f40 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
18f50 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
18f60 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
18f70 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
18f80 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
18f90 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
18fa0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
18fb0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
18fc0 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
18fd0 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
18fe0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
18ff0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
19000 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
19010 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
19020 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
19030 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
19040 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19050 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
19060 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
19070 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
19080 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
19090 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
190a0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
190b0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
190c0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
190d0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
190e0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
190f0 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
19100 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
19110 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
19120 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
19130 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
19140 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
19150 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
19160 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
19170 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
19180 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
19190 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
191a0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
191b0 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
191c0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
191d0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
191e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
191f0 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
19200 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  fied, inserted o
19210 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
19220 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
19230 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
19240 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
19250 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
19260 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  t on the databas
19270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
19280 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e  cified by the on
19290 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ly parameter..**
192a0 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
192b0 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
192c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
192d0 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
192e0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
192f0 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
19300 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  on..**.** ^Only 
19310 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72  changes made dir
19320 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53  ectly by the INS
19330 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
19340 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
19350 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
19360 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68  d - auxiliary ch
19370 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
19380 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
19390 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a  | triggers], .**
193a0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
193b0 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41  tions] or [REPLA
193c0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
193d0 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f  esolution are no
193e0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
193f0 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
19400 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
19410 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20  ercepted by .** 
19420 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
19430 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46  ger | INSTEAD OF
19440 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e   triggers] are n
19450 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65  ot counted. ^The
19460 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72   value .** retur
19470 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
19480 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61  hanges() immedia
19490 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e  tely after an IN
194a0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
194b0 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
194c0 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69  ment run on a vi
194d0 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  ew is always zer
194e0 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  o. Only changes 
194f0 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a  made to real .**
19500 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e   tables are coun
19510 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67  ted..**.** Thing
19520 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c  s are more compl
19530 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71  icated if the sq
19540 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
19550 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65  function is.** e
19560 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20  xecuted while a 
19570 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
19580 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73  is running. This
19590 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74   may happen if t
195a0 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  he.** program us
195b0 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  es the [changes(
195c0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c  ) SQL function],
195d0 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65   or if some othe
195e0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  r callback.** fu
195f0 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73  nction invokes s
19600 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19610 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e   directly. Essen
19620 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c  tially:.** .** <
19630 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ul>.**   <li> ^(
19640 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20  Before entering 
19650 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
19660 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  m the value retu
19670 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
19680 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65    sqlite3_change
19690 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  s() function is 
196a0 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65  saved. After the
196b0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
196c0 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20   .**        has 
196d0 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72  finished, the or
196e0 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20  iginal value is 
196f0 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a  restored.)^.** .
19700 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68  **   <li> ^(With
19710 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  in a trigger pro
19720 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54  gram each INSERT
19730 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c  , UPDATE and DEL
19740 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73  ETE .**        s
19750 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68  tatement sets th
19760 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19770 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
19780 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
19790 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e   upon completion
197a0 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63   as normal. Of c
197b0 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75  ourse, this valu
197c0 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75  e will not inclu
197d0 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e  de .**        an
197e0 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72  y changes perfor
197f0 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67  med by sub-trigg
19800 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69  ers, as the sqli
19810 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
19820 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77  *        value w
19830 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64  ill be saved and
19840 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20   restored after 
19850 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72  each sub-trigger
19860 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c   has run.)^.** <
19870 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69  /ul>.** .** ^Thi
19880 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20  s means that if 
19890 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51  the changes() SQ
198a0 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73  L function (or s
198b0 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a  imilar) is used.
198c0 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
198d0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
198e0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
198f0 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
19900 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75  ger, it .** retu
19910 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73  rns the value as
19920 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61   set when the ca
19930 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  lling statement 
19940 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e  began executing.
19950 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73  .** ^If it is us
19960 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
19970 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73   or subsequent s
19980 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69  uch statement wi
19990 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a  thin a trigger .
199a0 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20  ** program, the 
199b0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72  value returned r
199c0 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62  eflects the numb
199d0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
199e0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70  ied by the .** p
199f0 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20  revious INSERT, 
19a00 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
19a10 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
19a20 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  n the same trigg
19a30 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
19a40 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
19a50 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
19a60 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
19a70 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
19a80 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
19a90 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
19aa0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
19ab0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
19ac0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
19ad0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
19ae0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19af0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
19b00 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19b10 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
19b20 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
19b30 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
19b40 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
19b50 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
19b60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
19b70 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
19b80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19b90 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
19ba0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
19bb0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
19bc0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
19bd0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
19be0 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
19bf0 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64  of rows inserted
19c00 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a  , modified or.**
19c10 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20   deleted by all 
19c20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
19c30 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
19c40 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65  tatements comple
19c50 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ted.** since the
19c60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19c70 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c  tion was opened,
19c80 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65   including those
19c90 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20   executed as.** 
19ca0 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20  part of trigger 
19cb0 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75  programs. ^Execu
19cc0 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
19cd0 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
19ce0 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ment.** does not
19cf0 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75   affect the valu
19d00 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
19d10 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
19d20 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43  ges()..** .** ^C
19d30 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70  hanges made as p
19d40 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20  art of [foreign 
19d50 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
19d60 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
19d70 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74  .** count, but t
19d80 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72  hose made as par
19d90 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e  t of REPLACE con
19da0 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
19db0 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e  on are.** not. ^
19dc0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
19dd0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
19de0 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41  cepted by INSTEA
19df0 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a  D OF triggers .*
19e00 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
19e10 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c  d..** .** See al
19e20 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
19e30 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
19e40 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
19e50 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
19e60 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
19e70 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
19e80 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
19e90 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
19ea0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
19eb0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
19ec0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19ed0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
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 73 20 72 75 6e 6e  anges()] is runn
19f00 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
19f10 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
19f20 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
19f30 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
19f40 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
19f50 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
19f60 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19f70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
19f80 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
19f90 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d  nning Query.** M
19fa0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
19fb0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
19fc0 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
19fd0 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
19fe0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
19ff0 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
1a000 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
1a010 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
1a020 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
1a030 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
1a040 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
1a050 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
1a060 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
1a070 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
1a080 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
1a090 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
1a0a0 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
1a0b0 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
1a0c0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
1a0d0 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
1a0e0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
1a0f0 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
1a100 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
1a110 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
1a120 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
1a130 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
1a140 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
1a150 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
1a160 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1a170 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1a180 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a190 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
1a1a0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
1a1b0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
1a1c0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a1d0 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
1a1e0 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
1a1f0 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
1a200 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
1a210 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
1a220 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
1a230 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
1a240 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
1a250 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
1a260 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
1a270 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
1a280 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
1a290 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
1a2a0 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
1a2b0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
1a2c0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
1a2d0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
1a2e0 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
1a2f0 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
1a300 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
1a310 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
1a320 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
1a330 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
1a340 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
1a350 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
1a360 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
1a370 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
1a380 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
1a390 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
1a3a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1a3b0 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
1a3c0 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
1a3d0 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
1a3e0 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
1a3f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
1a400 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1a410 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
1a420 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
1a430 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1a440 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1a450 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1a460 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1a470 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
1a480 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
1a490 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
1a4a0 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
1a4b0 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
1a4c0 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
1a4d0 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
1a4e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a4f0 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
1a500 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1a510 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1a520 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
1a530 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
1a540 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
1a550 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
1a560 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
1a570 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a580 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
1a590 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a5a0 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
1a5b0 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
1a5c0 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
1a5d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
1a5e0 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
1a5f0 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
1a600 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1a610 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1a620 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1a630 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1a640 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
1a650 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
1a660 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
1a670 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
1a680 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
1a690 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
1a6a0 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
1a6b0 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
1a6c0 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
1a6d0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
1a6e0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1a6f0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1a700 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1a710 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
1a720 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
1a730 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
1a740 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
1a750 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
1a760 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
1a770 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
1a780 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
1a790 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
1a7a0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1a7b0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
1a7c0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
1a7d0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
1a7e0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
1a7f0 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
1a800 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
1a810 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1a820 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
1a830 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
1a840 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
1a850 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1a860 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
1a870 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
1a880 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
1a890 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
1a8a0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
1a8b0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
1a8c0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
1a8d0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
1a8e0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
1a8f0 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
1a900 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
1a910 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
1a920 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
1a930 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
1a940 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
1a950 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
1a960 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
1a970 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
1a980 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
1a990 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
1a9a0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
1a9b0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
1a9c0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
1a9d0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
1a9e0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
1a9f0 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
1aa00 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
1aa10 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
1aa20 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
1aa30 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1aa40 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
1aa50 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
1aa60 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
1aa70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1aa80 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
1aa90 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
1aaa0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
1aab0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
1aac0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
1aad0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
1aae0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
1aaf0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
1ab00 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
1ab10 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
1ab20 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
1ab30 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
1ab40 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
1ab50 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
1ab60 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
1ab70 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1ab80 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
1ab90 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
1aba0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
1abb0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
1abc0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1abd0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
1abe0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
1abf0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
1ac00 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
1ac10 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1ac20 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
1ac30 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
1ac40 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1ac50 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1ac60 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1ac70 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1ac80 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1ac90 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1aca0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1acb0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1acc0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1acd0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1ace0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1acf0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1ad00 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1ad10 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1ad20 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1ad30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1ad40 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
1ad50 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
1ad60 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1ad70 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
1ad80 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1ad90 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
1ada0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
1adb0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
1adc0 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  rrors.** KEYWORD
1add0 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72  S: {busy-handler
1ade0 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79   callback} {busy
1adf0 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54   handler}.** MET
1ae00 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1ae10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1ae20 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58  busy_handler(D,X
1ae30 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73  ,P) routine sets
1ae40 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1ae50 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d  tion X.** that m
1ae60 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1ae70 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
1ae80 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
1ae90 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1aea0 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62  o access a datab
1aeb0 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69  ase table associ
1aec0 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61  ated with.** [da
1aed0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1aee0 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65  n] D when anothe
1aef0 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
1af00 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74  rocess has the t
1af10 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20  able locked..** 
1af20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1af30 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72  _handler() inter
1af40 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
1af50 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71  implement.** [sq
1af60 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1af70 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d  ut()] and [PRAGM
1af80 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e  A busy_timeout].
1af90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
1afa0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1afb0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
1afc0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72  TE_BUSY].** is r
1afd0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1afe0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
1aff0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
1b000 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1b010 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
1b020 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1b030 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
1b040 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
1b050 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
1b060 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1b070 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
1b080 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
1b090 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
1b0a0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
1b0b0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
1b0c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1b0d0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1b0e0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
1b0f0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
1b100 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1b110 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1b120 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
1b130 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
1b140 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
1b150 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76  een invoked prev
1b160 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73  iously for the s
1b170 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
1b180 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
1b190 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
1b1a0 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
1b1b0 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
1b1c0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
1b1d0 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
1b1e0 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
1b1f0 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75  TE_BUSY] is retu
1b200 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61  rned.** to the a
1b210 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  pplication..** ^
1b220 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1b230 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1b240 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
1b250 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
1b260 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  e to access the 
1b270 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65  database and the
1b280 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
1b290 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
1b2a0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
1b2b0 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
1b2c0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
1b2d0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
1b2e0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
1b2f0 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
1b300 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
1b310 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
1b320 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
1b330 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
1b340 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
1b350 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
1b360 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
1b370 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1b380 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1b390 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66  ation instead of
1b3a0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a   invoking the .*
1b3b0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
1b3c0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1b3d0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1b3e0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1b3f0 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1b400 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1b410 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1b420 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1b430 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1b440 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1b450 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1b460 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1b470 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1b480 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1b490 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1b4a0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1b4b0 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1b4c0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1b4d0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1b4e0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1b4f0 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1b500 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1b510 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1b520 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1b530 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1b540 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1b550 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1b560 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1b570 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1b580 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1b590 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1b5a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1b5b0 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1b5c0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1b5d0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1b5e0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1b5f0 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1b600 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1b610 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1b620 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1b630 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1b640 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1b650 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1b660 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  NULL..**.** ^(Th
1b670 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1b680 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1b690 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
1b6a0 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
1b6b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1b6c0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
1b6d0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
1b6e0 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
1b6f0 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
1b700 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
1b710 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1b720 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1b730 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69  ].** or evaluati
1b740 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  ng [PRAGMA busy_
1b750 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20  timeout=N] will 
1b760 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75  change the.** bu
1b770 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74  sy handler and t
1b780 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72  hus clear any pr
1b790 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73  eviously set bus
1b7a0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1b7b0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1b7c0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1b7d0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1b7e0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1b7f0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1b800 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1b810 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1b820 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  dler.  In other 
1b830 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75  words,.** the bu
1b840 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f  sy handler is no
1b850 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e  t reentrant.  An
1b860 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
1b870 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
1b880 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
1b890 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
1b8a0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
1b8b0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
1b8c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1b8d0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
1b8e0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
1b8f0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1b900 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
1b910 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1b920 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28  er(sqlite3*,int(
1b930 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f  *)(void*,int),vo
1b940 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1b950 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1b960 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1b970 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1b980 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1b990 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1b9a0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1b9b0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1b9c0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1b9d0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1b9e0 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1b9f0 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1ba00 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1ba10 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1ba20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1ba30 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1ba40 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1ba50 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1ba60 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1ba70 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1ba80 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1ba90 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1baa0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1bab0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1bac0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1bad0 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1bae0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1baf0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1bb00 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1bb10 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1bb20 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1bb30 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1bb40 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1bb50 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1bb60 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1bb70 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1bb80 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1bb90 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1bba0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1bbb0 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
1bbc0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1bbd0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1bbe0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1bbf0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1bc00 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1bc10 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1bc20 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1bc30 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1bc40 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1bc50 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
1bc60 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
1bc70 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1bc80 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ut].*/.int sqlit
1bc90 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1bca0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1bcb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bcc0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1bcd0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1bce0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
1bcf0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1bd00 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1bd10 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1bd20 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1bd30 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1bd40 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1bd50 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1bd60 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1bd70 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1bd80 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1bd90 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1bda0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1bdb0 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1bdc0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1bdd0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1bde0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1bdf0 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1be00 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1be10 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1be20 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1be30 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1be40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1be50 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1be60 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1be70 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1be80 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1be90 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1bea0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1beb0 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1bec0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1bed0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1bee0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1bef0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1bf00 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1bf10 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1bf20 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1bf30 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1bf40 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1bf50 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1bf60 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1bf70 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1bf80 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1bf90 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1bfa0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1bfb0 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1bfc0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1bfd0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1bfe0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1bff0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1c000 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1c010 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1c020 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1c030 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1c040 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1c050 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1c060 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1c070 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1c080 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1c090 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1c0a0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1c0b0 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1c0c0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1c0d0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1c0e0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c0f0 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1c100 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1c110 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1c120 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1c130 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1c140 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1c150 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1c160 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1c170 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1c180 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1c190 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1c1a0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1c1b0 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1c1c0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1c1d0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1c1e0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1c1f0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1c200 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1c210 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1c220 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1c230 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1c240 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1c250 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1c260 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1c270 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1c280 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1c290 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1c2a0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1c2b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c2c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1c2d0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1c2e0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1c2f0 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1c300 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1c310 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1c320 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1c330 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1c340 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1c350 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1c360 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1c370 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1c380 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1c390 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1c3a0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1c3b0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1c3c0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1c3d0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c3e0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1c3f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1c400 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1c410 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c420 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1c430 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1c440 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1c450 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1c460 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1c470 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1c480 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1c490 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1c4a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c4b0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1c4c0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1c4d0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1c4e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1c4f0 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1c500 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1c510 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1c520 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1c530 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1c540 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1c550 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1c560 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1c570 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1c580 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1c590 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1c5a0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1c5b0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1c5c0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1c5d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1c5e0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1c5f0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1c600 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1c610 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1c620 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1c630 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1c640 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1c650 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1c660 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1c670 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1c680 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1c690 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1c6a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1c6b0 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1c6c0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1c6d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1c6e0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1c6f0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1c700 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1c710 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1c720 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1c730 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1c740 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1c750 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1c760 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1c770 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1c780 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1c790 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1c7a0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1c7b0 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1c7c0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1c7d0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1c7e0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1c7f0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1c800 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1c810 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1c820 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1c830 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1c840 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1c850 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1c860 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1c870 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1c880 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1c890 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1c8a0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1c8b0 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1c8c0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1c8d0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1c8e0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1c8f0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1c900 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1c910 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1c920 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1c930 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
1c940 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1c950 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1c960 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1c970 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1c980 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1c990 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1c9a0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1c9b0 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1c9c0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1c9d0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1c9e0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1c9f0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1ca00 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1ca10 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1ca20 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1ca30 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1ca40 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1ca50 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1ca60 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1ca70 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1ca80 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1ca90 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1caa0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1cab0 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1cac0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1cad0 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1cae0 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1caf0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1cb00 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1cb10 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1cb20 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1cb30 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1cb40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1cb50 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1cb60 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73  library..** Thes
1cb70 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72  e routines under
1cb80 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68  stand most of th
1cb90 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72  e common K&R for
1cba0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c  matting options,
1cbb0 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64  .** plus some ad
1cbc0 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61  ditional non-sta
1cbd0 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64  ndard formats, d
1cbe0 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a  etailed below..*
1cbf0 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65  * Note that some
1cc00 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73   of the more obs
1cc10 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20  cure formatting 
1cc20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63  options from rec
1cc30 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79  ent.** C-library
1cc40 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f   standards are o
1cc50 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73  mitted from this
1cc60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1cc70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1cc80 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1cc90 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1cca0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1ccb0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1ccc0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1ccd0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1cce0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1ccf0 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1cd00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1cd10 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1cd20 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1cd30 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1cd40 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1cd50 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1cd60 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1cd70 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1cd80 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
1cd90 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1cda0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1cdb0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1cdc0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1cdd0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1cde0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1cdf0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1ce00 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1ce10 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1ce20 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1ce30 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1ce40 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1ce50 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1ce60 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1ce70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1ce80 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1ce90 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1cea0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1ceb0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1cec0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1ced0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1cee0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1cef0 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1cf00 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1cf10 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1cf20 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1cf30 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1cf40 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1cf50 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1cf60 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1cf70 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1cf80 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1cf90 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1cfa0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1cfb0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1cfc0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1cfd0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1cfe0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1cff0 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1d000 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1d010 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1d020 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1d030 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1d040 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1d050 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1d060 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1d070 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1d080 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1d090 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1d0a0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1d0b0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1d0c0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1d0d0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1d0e0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1d0f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1d100 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1d110 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1d120 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1d130 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1d140 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1d150 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1d160 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1d170 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1d180 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1d190 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1d1a0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1d1b0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1d1c0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1d1d0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1d1e0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1d1f0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1d200 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1d210 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1d220 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1d230 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1d240 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
1d250 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
1d260 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
1d270 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1d280 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1d290 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1d2a0 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1d2b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1d2c0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1d2d0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1d2e0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1d2f0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1d300 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1d310 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1d320 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20  , "%w" and "%z" 
1d330 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1d340 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1d350 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1d360 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1d370 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1d380 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1d390 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1d3a0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1d3b0 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1d3c0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1d3d0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1d3e0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1d3f0 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1d400 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1d410 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1d420 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1d430 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1d440 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1d450 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1d460 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1d470 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1d480 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1d490 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1d4a0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1d4b0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1d4c0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1d4d0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1d4e0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1d4f0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1d500 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1d510 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1d520 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1d530 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1d540 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1d550 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1d560 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1d570 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1d580 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1d590 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1d5a0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1d5b0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1d5c0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1d5d0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1d5e0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1d5f0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1d600 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1d610 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1d620 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1d630 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1d640 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1d650 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1d660 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1d670 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1d680 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1d690 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1d6a0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1d6b0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1d6c0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1d6d0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1d6e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1d6f0 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1d700 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1d710 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1d720 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1d730 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1d740 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1d750 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1d760 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1d770 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1d780 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1d790 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1d7a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1d7b0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1d7c0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1d7d0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1d7e0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1d7f0 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1d800 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1d810 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1d820 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1d830 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1d840 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1d850 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1d860 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1d870 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1d880 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1d890 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1d8a0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1d8b0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1d8c0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1d8d0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1d8e0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1d8f0 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1d900 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1d910 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1d920 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1d930 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1d940 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1d950 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1d960 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1d970 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1d980 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1d990 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1d9a0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1d9b0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1d9c0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1d9d0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1d9e0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1d9f0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1da00 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1da10 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1da20 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1da30 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1da40 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1da50 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1da60 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1da70 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1da80 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1da90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1daa0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66  .** ^(The "%w" f
1dab0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1dac0 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78   is like "%q" ex
1dad0 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70  cept that it exp
1dae0 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f  ects to.** be co
1daf0 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64  ntained within d
1db00 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73  ouble-quotes ins
1db10 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71  tead of single q
1db20 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a  uotes, and it.**
1db30 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75   escapes the dou
1db40 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63  ble-quote charac
1db50 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ter instead of t
1db60 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a  he single-quote.
1db70 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20  ** character.)^ 
1db80 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74   The "%w" format
1db90 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69  ting option is i
1dba0 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65  ntended for safe
1dbb0 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20  ly inserting.** 
1dbc0 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
1dbd0 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f   names into a co
1dbe0 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74  nstructed SQL st
1dbf0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  atement..**.** ^
1dc00 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1dc10 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1dc20 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1dc30 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1dc40 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1dc50 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1dc60 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1dc70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1dc80 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1dc90 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1dca0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1dcb0 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
1dcc0 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1dcd0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1dce0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1dcf0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1dd00 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1dd10 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1dd20 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1dd30 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1dd40 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
1dd50 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1dd60 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1dd70 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1dd80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1dd90 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1dda0 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1ddb0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1ddc0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1ddd0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1dde0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1ddf0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1de00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1de10 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1de20 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1de30 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1de40 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1de50 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1de60 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1de70 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1de80 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1de90 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1dea0 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1deb0 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1dec0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1ded0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1dee0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1def0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1df00 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1df10 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1df20 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1df30 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1df40 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1df50 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1df60 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1df70 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1df80 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1df90 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1dfa0 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1dfb0 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1dfc0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1dfd0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1dfe0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1dff0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1e000 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1e010 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1e020 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1e030 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1e040 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1e050 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e060 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1e070 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1e080 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1e090 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1e0a0 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1e0b0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1e0c0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1e0d0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1e0e0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1e0f0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1e100 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1e110 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1e120 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1e130 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1e140 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1e150 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1e160 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1e170 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1e180 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1e190 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1e1a0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1e1b0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1e1c0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1e1d0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1e1e0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1e1f0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1e200 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1e210 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1e220 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1e230 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1e240 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1e250 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1e260 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1e270 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1e280 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1e290 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1e2a0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1e2b0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1e2c0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1e2d0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1e2e0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1e2f0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1e300 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1e310 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1e320 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1e330 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1e340 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1e350 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e360 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1e370 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1e380 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1e390 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1e3a0 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1e3b0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1e3c0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1e3d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1e3e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1e3f0 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1e400 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1e410 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1e420 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1e430 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1e440 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1e450 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1e460 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1e470 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1e480 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1e490 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1e4a0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1e4b0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1e4c0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1e4d0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1e4e0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1e4f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1e500 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1e510 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1e520 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1e530 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1e540 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1e550 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1e560 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1e570 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1e580 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1e590 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1e5a0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1e5b0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1e5c0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1e5d0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1e5e0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1e5f0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1e600 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1e610 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1e620 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1e630 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1e640 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1e650 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1e660 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1e670 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1e680 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1e690 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1e6a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1e6b0 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1e6c0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1e6d0 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1e6e0 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1e6f0 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1e700 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1e710 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1e720 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1e730 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1e740 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1e750 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1e760 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1e770 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1e780 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1e790 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1e7a0 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1e7b0 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1e7c0 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1e7d0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1e7e0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1e7f0 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1e800 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1e810 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1e820 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1e830 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1e840 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1e850 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1e860 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1e870 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1e880 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1e890 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1e8a0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1e8b0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1e8c0 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1e8d0 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1e8e0 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1e8f0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1e900 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1e910 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1e920 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1e930 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1e940 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1e950 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1e960 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1e970 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1e980 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1e990 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1e9a0 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1e9b0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1e9c0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1e9d0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1e9e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1e9f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1ea00 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1ea10 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1ea20 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1ea30 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1ea40 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1ea50 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1ea60 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1ea70 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1ea80 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1ea90 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1eaa0 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1eab0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1eac0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1ead0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1eae0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1eaf0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1eb00 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1eb10 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1eb20 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1eb30 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1eb40 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1eb50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1eb60 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1eb70 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1eb80 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1eb90 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1eba0 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1ebb0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1ebc0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1ebd0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1ebe0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1ebf0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1ec00 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1ec10 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1ec20 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1ec30 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1ec40 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1ec50 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1ec60 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1ec70 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1ec80 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1ec90 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1eca0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1ecb0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1ecc0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1ecd0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1ece0 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1ecf0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1ed00 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1ed10 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1ed20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1ed30 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1ed40 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1ed50 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1ed60 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1ed70 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1ed80 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1ed90 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1eda0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1edb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1edc0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1edd0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1ede0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1edf0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1ee00 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1ee10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1ee20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1ee30 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1ee40 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1ee50 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1ee60 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1ee70 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1ee80 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1ee90 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1eea0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1eeb0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1eec0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1eed0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1eee0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1eef0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
1ef00 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1ef10 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
1ef20 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
1ef30 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
1ef40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1ef50 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1ef60 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1ef70 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c  realloc64(void*,
1ef80 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
1ef90 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1efa0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69  ree(void*);.sqli
1efb0 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  te3_uint64 sqlit
1efc0 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
1efd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1efe0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1eff0 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1f000 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1f010 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1f020 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1f030 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1f040 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1f050 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f060 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1f070 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1f080 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1f090 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1f0a0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1f0b0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1f0c0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1f0d0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1f0e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1f0f0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1f100 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1f110 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1f120 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1f130 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1f140 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1f150 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1f160 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1f170 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1f180 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1f190 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1f1a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1f1b0 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1f1c0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1f1d0 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1f1e0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1f1f0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1f200 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1f210 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1f220 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1f230 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1f240 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1f250 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1f260 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1f270 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1f280 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1f290 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1f2a0 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1f2b0 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1f2c0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1f2d0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1f2e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f2f0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1f300 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1f310 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1f320 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1f330 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1f340 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1f350 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1f360 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1f370 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1f380 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1f390 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1f3a0 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1f3b0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1f3c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1f3d0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1f3e0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1f3f0 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1f400 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
1f410 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1f420 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1f430 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
1f440 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1f450 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1f460 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1f470 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
1f480 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
1f490 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
1f4a0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
1f4b0 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
1f4c0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
1f4d0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
1f4e0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
1f4f0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
1f500 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
1f510 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
1f520 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
1f530 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
1f540 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
1f550 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
1f560 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
1f570 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
1f580 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
1f590 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
1f5a0 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
1f5b0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
1f5c0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
1f5d0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
1f5e0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
1f5f0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
1f600 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
1f610 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
1f620 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
1f630 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
1f640 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
1f650 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
1f660 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
1f670 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
1f680 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1f690 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
1f6a0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
1f6b0 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
1f6c0 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
1f6d0 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
1f6e0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
1f6f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1f700 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
1f710 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
1f720 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1f730 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
1f740 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
1f750 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
1f760 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1f770 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1f780 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
1f790 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
1f7a0 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
1f7b0 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
1f7c0 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
1f7d0 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
1f7e0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1f7f0 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1f800 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1f810 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1f820 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1f830 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1f840 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
1f850 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
1f860 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
1f870 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
1f880 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
1f890 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
1f8a0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  n Callbacks.** M
1f8b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1f8c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1f8d0 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
1f8e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1f8f0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
1f900 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1f910 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
1f920 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
1f930 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
1f940 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
1f950 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1f960 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
1f970 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
1f980 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
1f990 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1f9a0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1f9b0 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
1f9c0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
1f9d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f9e0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
1f9f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1fa00 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
1fa10 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
1fa20 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
1fa30 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
1fa40 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
1fa50 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
1fa60 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
1fa70 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
1fa80 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1fa90 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
1faa0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
1fab0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
1fac0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1fad0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1fae0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1faf0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
1fb00 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
1fb10 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
1fb20 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
1fb30 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
1fb40 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
1fb50 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
1fb60 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
1fb70 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
1fb80 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
1fb90 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
1fba0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1fbb0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
1fbc0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
1fbd0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
1fbe0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
1fbf0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
1fc00 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1fc10 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
1fc20 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
1fc30 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
1fc40 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
1fc50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1fc60 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1fc70 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
1fc80 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1fc90 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1fca0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1fcb0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1fcc0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1fcd0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
1fce0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
1fcf0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
1fd00 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
1fd10 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1fd20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1fd30 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
1fd40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fd50 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1fd60 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1fd70 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
1fd80 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1fd90 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1fda0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
1fdb0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
1fdc0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
1fdd0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1fde0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1fdf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fe00 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
1fe10 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
1fe20 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1fe30 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1fe40 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
1fe50 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
1fe60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
1fe70 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1fe80 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
1fe90 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
1fea0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1feb0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
1fec0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
1fed0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1fee0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
1fef0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1ff00 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
1ff10 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
1ff20 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1ff30 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
1ff40 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
1ff50 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
1ff60 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1ff70 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
1ff80 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1ff90 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
1ffa0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
1ffb0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1ffc0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1ffd0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
1ffe0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1fff0 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
20000 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
20010 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
20020 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
20030 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
20040 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
20050 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
20060 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
20070 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
20080 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
20090 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
200a0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
200b0 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
200c0 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
200d0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
200e0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
200f0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
20100 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
20110 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
20120 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
20130 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
20140 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
20150 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
20160 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
20170 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
20180 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
20190 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
201a0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
201b0 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
201c0 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
201d0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
201e0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
201f0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
20200 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
20210 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
20220 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
20230 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
20240 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
20250 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
20260 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
20270 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
20280 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
20290 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
202a0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
202b0 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
202c0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
202d0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
202e0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
202f0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
20300 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
20310 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
20320 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
20330 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
20340 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
20350 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
20360 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
20370 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
20380 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
20390 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
203a0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
203b0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
203c0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
203d0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
203e0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
203f0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
20400 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
20410 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
20420 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
20430 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
20440 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
20450 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
20460 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
20470 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
20480 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
20490 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
204a0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
204b0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
204c0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
204d0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
204e0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
204f0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
20500 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
20510 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
20520 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
20530 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
20540 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
20550 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
20560 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
20570 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
20580 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
20590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
205a0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
205b0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
205c0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
205d0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
205e0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
205f0 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
20600 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
20610 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
20620 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
20630 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
20640 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
20650 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
20660 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20670 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
20680 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
20690 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
206a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
206b0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
206c0 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
206d0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
206e0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
206f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20700 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
20710 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
20720 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
20730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
20740 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
20750 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
20760 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
20770 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
20780 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20790 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
207a0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
207b0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
207c0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
207d0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
207e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
207f0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
20800 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
20810 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
20820 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
20830 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
20840 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
20850 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
20860 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
20870 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
20880 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
20890 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
208a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
208b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
208c0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
208d0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
208e0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
208f0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
20900 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
20910 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
20920 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
20930 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
20940 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
20950 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
20960 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
20970 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
20980 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
20990 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
209a0 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
209b0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
209c0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
209d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
209e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
209f0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
20a00 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
20a10 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
20a20 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
20a30 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
20a40 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
20a50 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
20a60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
20a70 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
20a80 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
20a90 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
20aa0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
20ab0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
20ac0 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
20ad0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
20ae0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
20af0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
20b00 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
20b10 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
20b20 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
20b30 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
20b40 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
20b50 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
20b60 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
20b70 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
20b80 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
20b90 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
20ba0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
20bb0 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
20bc0 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
20bd0 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e  o used as a [con
20be0 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e  flict resolution
20bf0 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e   mode].** return
20c00 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ed from the [sql
20c10 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
20c20 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
20c30 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
20c40 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
20c50 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
20c60 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
20c70 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
20c80 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
20c90 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
20ca0 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
20cb0 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
20cc0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
20cd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
20ce0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
20cf0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
20d00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
20d10 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
20d20 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
20d30 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20d40 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
20d50 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
20d60 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
20d70 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
20d80 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
20d90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20da0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
20db0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
20dc0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
20dd0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
20de0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
20df0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
20e00 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
20e10 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
20e20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20e30 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
20e40 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
20e50 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
20e60 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
20e70 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
20e80 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
20e90 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
20ea0 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
20eb0 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
20ec0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
20ed0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
20ee0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
20ef0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
20f00 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
20f10 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
20f20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
20f30 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
20f40 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
20f50 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
20f60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20f70 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
20f80 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
20f90 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
20fa0 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
20fb0 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
20fc0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
20fd0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
20fe0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
20ff0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
21000 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
21010 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
21020 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
21030 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
21040 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
21050 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
21060 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
21070 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
21080 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
21090 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
210a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
210b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
210c0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
210d0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
210e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
210f0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
21100 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
21110 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
21120 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21130 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21140 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
21150 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
21160 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21170 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21180 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21190 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
211a0 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
211b0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
211c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
211d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
211e0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
211f0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
21200 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21210 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21220 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21230 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
21240 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
21250 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
21260 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21270 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21280 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
21290 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
212a0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
212b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
212c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
212d0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
212e0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
212f0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
21300 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21310 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21320 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
21330 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
21340 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21350 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21360 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
21370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
21380 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21390 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
213a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
213b0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
213c0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
213d0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
213e0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
213f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21400 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
21410 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
21420 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21430 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21440 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21450 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
21460 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
21470 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
21480 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21490 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
214a0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
214b0 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
214c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
214d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
214e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
214f0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
21500 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
21510 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
21520 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21530 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21540 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
21550 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
21560 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
21570 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21580 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21590 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
215a0 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
215b0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
215c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
215d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
215e0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
215f0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
21600 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
21610 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21620 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21630 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
21640 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
21650 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21660 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21670 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
21680 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
21690 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
216a0 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
216b0 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
216c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
216d0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
216e0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
216f0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
21700 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
21710 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
21720 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
21730 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
21740 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
21750 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21760 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
21770 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
21780 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
21790 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
217a0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
217b0 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
217c0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
217d0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
217e0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
217f0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
21800 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
21810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
21820 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
21830 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21840 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21850 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
21860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
21870 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
21880 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
21890 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
218a0 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
218b0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
218c0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
218d0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
218e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
218f0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
21900 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
21910 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
21920 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21930 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21940 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
21950 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
21960 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21970 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21980 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21990 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
219a0 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
219b0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
219c0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
219d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
219e0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
219f0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
21a00 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21a10 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
21a20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21a30 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
21a40 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
21a50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21a60 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
21a70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21a80 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
21a90 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
21aa0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
21ab0 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
21ac0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21ad0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
21ae0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
21af0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
21b00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
21b10 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
21b20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c      33   /* NULL
21b30 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
21b40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a              */..
21b50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21b60 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
21b70 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
21b80 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
21b90 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e3.**.** These r
21ba0 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 72  outines are depr
21bb0 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 20  ecated. Use the 
21bc0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
21bd0 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  2()] interface.*
21be0 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  * instead of the
21bf0 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69   routines descri
21c00 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  bed here..**.** 
21c10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
21c20 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
21c30 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
21c40 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
21c50 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
21c60 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
21c70 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
21c80 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
21c90 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
21ca0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
21cb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
21cc0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
21cd0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
21ce0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
21cf0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
21d00 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
21d10 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
21d20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
21d30 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
21d40 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
21d50 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
21d60 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
21d70 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
21d80 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
21d90 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
21da0 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
21db0 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
21dc0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
21dd0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
21de0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
21df0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
21e00 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
21e10 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
21e20 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
21e30 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
21e40 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
21e50 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
21e60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
21e70 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
21e80 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
21e90 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
21ea0 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
21eb0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
21ec0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
21ed0 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
21ee0 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
21ef0 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
21f00 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
21f10 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
21f20 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
21f30 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
21f40 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
21f50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
21f60 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
21f70 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
21f80 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
21f90 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
21fa0 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
21fb0 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
21fc0 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
21fd0 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
21fe0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
21ff0 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
22000 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
22010 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
22020 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
22030 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
22040 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
22050 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
22060 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
22070 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
22080 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
22090 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
220a0 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
220b0 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
220c0 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
220d0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
220e0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
220f0 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
22100 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
22110 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
22120 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
22130 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
22140 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
22150 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
22160 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
22170 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
22180 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
22190 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44  ite..*/.SQLITE_D
221a0 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a  EPRECATED void *
221b0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
221c0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
221d0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
221e0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
221f0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  d*);.SQLITE_DEPR
22200 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c  ECATED void *sql
22210 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
22220 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
22230 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
22240 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
22250 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
22260 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
22270 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20  3REF: SQL Trace 
22280 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  Event Codes.** K
22290 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
222a0 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73  TRACE.**.** Thes
222b0 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e  e constants iden
222c0 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20  tify classes of 
222d0 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20  events that can 
222e0 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20  be monitored.** 
222f0 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
22300 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74  e3_trace_v2()] t
22310 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54  racing logic.  T
22320 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
22330 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
22340 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20  _trace_v2()] is 
22350 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61  an OR-ed combina
22360 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  tion of one or m
22370 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  ore of.** the fo
22380 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74  llowing constant
22390 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61  s.  ^The first a
223a0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74  rgument to the t
223b0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  race callback.**
223c0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   is one of the f
223d0 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e  ollowing constan
223e0 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72  ts..**.** New tr
223f0 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  acing constants 
22400 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
22410 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
22420 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20  .**.** ^A trace 
22430 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75  callback has fou
22440 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61  r arguments: xCa
22450 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
22460 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
22470 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
22480 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63  e integer type c
22490 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e  odes above..** ^
224a0 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69  The C argument i
224b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
224c0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20  context pointer 
224d0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
224e0 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d  .** fourth argum
224f0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
22500 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  trace_v2()]..** 
22510 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
22520 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
22530 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
22540 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
22550 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
22560 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
22570 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
22580 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a  ACE_STMT</dt>.**
22590 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
225a0 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62  TRACE_STMT callb
225b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
225c0 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73  hen a prepared s
225d0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73  tatement.** firs
225e0 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67  t begins running
225f0 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74   and possibly at
22600 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72   other times dur
22610 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75  ing the.** execu
22620 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70  tion of the prep
22630 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20  ared statement, 
22640 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73  such as at the s
22650 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  tart of each.** 
22660 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
22670 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d  am. ^The P argum
22680 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
22690 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   to the.** [prep
226a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
226b0 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74   ^The X argument
226c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
226d0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a   a string which.
226e0 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61  ** is the unexpa
226f0 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66  nded SQL text of
22700 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
22710 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51  atement or an SQ
22720 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68  L comment .** th
22730 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65  at indicates the
22740 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61   invocation of a
22750 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20   trigger.  ^The 
22760 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d  callback can com
22770 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65  pute.** the same
22780 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64   text that would
22790 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72   have been retur
227a0 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63  ned by the legac
227b0 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  y [sqlite3_trace
227c0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
227d0 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20   by using the X 
227e0 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20  argument when X 
227f0 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22  begins with "--"
22800 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a   and invoking.**
22810 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   [sqlite3_expand
22820 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72  ed_sql(P)] other
22830 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  wise..**.** [[SQ
22840 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
22850 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  LE]] <dt>SQLITE_
22860 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64  TRACE_PROFILE</d
22870 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
22880 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
22890 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76  LE callback prov
228a0 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65  ides approximate
228b0 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69  ly the same.** i
228c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73  nformation as is
228d0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
228e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
228f0 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  e()] callback..*
22900 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
22910 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
22920 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
22930 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74  statement] and t
22940 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74  he.** X argument
22950 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d   points to a 64-
22960 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63  bit integer whic
22970 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74  h is the estimat
22980 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d  ed of.** the num
22990 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  ber of nanosecon
229a0 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61  d that the prepa
229b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  red statement to
229c0 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54  ok to run..** ^T
229d0 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  he SQLITE_TRACE_
229e0 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b  PROFILE callback
229f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
22a00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
22a10 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  inishes..**.** [
22a20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  [SQLITE_TRACE_RO
22a30 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  W]] <dt>SQLITE_T
22a40 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a  RACE_ROW</dt>.**
22a50 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
22a60 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61  TRACE_ROW callba
22a70 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
22a80 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65  enever a prepare
22a90 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67  d.** statement g
22aa0 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c  enerates a singl
22ab0 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e  e row of result.
22ac0 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67    .** ^The P arg
22ad0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
22ae0 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  er to the [prepa
22af0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
22b00 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75  nd the.** X argu
22b10 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a  ment is unused..
22b20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
22b30 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74  RACE_CLOSE]] <dt
22b40 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  >SQLITE_TRACE_CL
22b50 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  OSE</dt>.** <dd>
22b60 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
22b70 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20  _CLOSE callback 
22b80 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
22b90 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  a database.** co
22ba0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
22bb0 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
22bc0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
22bd0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
22be0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
22bf0 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ject.** and the 
22c00 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e  X argument is un
22c10 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  used..** </dl>.*
22c20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22c30 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20  _TRACE_STMT     
22c40 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53    0x01.#define S
22c50 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
22c60 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66  ILE    0x02.#def
22c70 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
22c80 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34  _ROW        0x04
22c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22ca0 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20  TRACE_CLOSE     
22cb0 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   0x08../*.** CAP
22cc0 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65  I3REF: SQL Trace
22cd0 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Hook.** METHOD:
22ce0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
22cf0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
22d00 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e  e_v2(D,M,X,P) in
22d10 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
22d20 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61  s a trace callba
22d30 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
22d40 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61   against [databa
22d50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
22d60 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79  , using property
22d70 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63   mask M.** and c
22d80 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50  ontext pointer P
22d90 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c  .  ^If the X cal
22da0 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c  lback is.** NULL
22db0 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73   or if the M mas
22dc0 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  k is zero, then 
22dd0 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62  tracing is disab
22de0 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61  led.  The.** M a
22df0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
22e00 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52  e the bitwise OR
22e10 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  -ed combination 
22e20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f  of.** zero or mo
22e30 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  re [SQLITE_TRACE
22e40 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  ] constants..**.
22e50 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f  ** ^Each call to
22e60 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
22e70 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74  trace() or sqlit
22e80 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76  e3_trace_v2() ov
22e90 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e  errides .** (can
22ea0 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20  cels) any prior 
22eb0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
22ec0 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69  _trace() or sqli
22ed0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a  te3_trace_v2()..
22ee0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c  **.** ^The X cal
22ef0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22f00 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66   whenever any of
22f10 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e   the events iden
22f20 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61  tified by .** ma
22f30 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68  sk M occur.  ^Th
22f40 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e  e integer return
22f50 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20   value from the 
22f60 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72  callback is curr
22f70 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64  ently.** ignored
22f80 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61  , though this ma
22f90 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  y change in futu
22fa0 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61  re releases.  Ca
22fb0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d  llback.** implem
22fc0 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
22fd0 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20   return zero to 
22fe0 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f  ensure future co
22ff0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
23000 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c  ** ^A trace call
23010 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
23020 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65  with four argume
23030 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c  nts: callback(T,
23040 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20  C,P,X)..** ^The 
23050 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  T argument is on
23060 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
23070 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74  _TRACE].** const
23080 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65  ants to indicate
23090 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63   why the callbac
230a0 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  k was invoked..*
230b0 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e  * ^The C argumen
230c0 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  t is a copy of t
230d0 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  he context point
230e0 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64  er..** The P and
230f0 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65   X arguments are
23100 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20   pointers whose 
23110 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20  meanings depend 
23120 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  on T..**.** The 
23130 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23140 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
23150 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c  intended to repl
23160 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  ace the legacy.*
23170 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
23180 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61  lite3_trace()] a
23190 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  nd [sqlite3_prof
231a0 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20  ile()], both of 
231b0 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70  which.** are dep
231c0 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20  recated..*/.int 
231d0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
231e0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
231f0 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a  unsigned uMask,.
23200 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b    int(*xCallback
23210 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a  )(unsigned,void*
23220 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20  ,void*,void*),. 
23230 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a   void *pCtx.);..
23240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23250 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
23260 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
23270 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
23280 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
23290 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
232a0 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
232b0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
232c0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
232d0 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
232e0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
232f0 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
23300 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
23310 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
23320 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
23330 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
23340 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
23350 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
23360 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
23370 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
23380 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
23390 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
233a0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
233b0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
233c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
233d0 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
233e0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
233f0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
23400 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
23410 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
23420 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
23430 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d   is the approxim
23440 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  ate number of .*
23450 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
23460 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
23470 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
23480 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
23490 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
234a0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
234b0 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20  lback X.  ^If N 
234c0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
234d0 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
234e0 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73  ss.** handler is
234f0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
23500 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
23510 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23520 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
23530 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
23540 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
23550 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
23560 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
23570 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
23580 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
23590 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
235a0 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
235b0 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
235c0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
235d0 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
235e0 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
235f0 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
23600 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
23610 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
23620 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
23630 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
23640 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
23650 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
23660 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
23670 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
23680 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
23690 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
236a0 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
236b0 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
236c0 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
236d0 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
236e0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
236f0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
23700 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
23710 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
23720 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23730 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
23740 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
23750 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
23760 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
23770 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
23780 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
23790 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
237a0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
237b0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
237c0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
237d0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
237e0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
237f0 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
23800 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
23810 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
23820 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
23830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23840 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
23850 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
23860 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  ion.** CONSTRUCT
23870 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
23880 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
23890 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
238a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
238b0 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
238c0 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
238d0 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
238e0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
238f0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
23900 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
23910 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
23920 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
23930 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
23940 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
23950 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
23960 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
23970 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
23980 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
23990 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
239a0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
239b0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
239c0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
239d0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
239e0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
239f0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
23a00 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
23a10 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
23a20 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
23a30 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
23a40 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
23a50 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
23a60 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
23a70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
23a80 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
23a90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
23aa0 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
23ab0 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
23ac0 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
23ad0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
23ae0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
23af0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
23b00 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
23b10 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
23b20 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
23b30 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
23b40 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
23b50 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
23b60 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
23b70 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
23b80 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
23b90 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
23ba0 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
23bb0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
23bc0 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
23bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
23be0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69  ault encoding wi
23bf0 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20  ll be UTF-8 for 
23c00 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65  databases create
23c10 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  d using.** sqlit
23c20 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
23c30 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
23c40 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
23c50 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62  coding for datab
23c60 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  ases.** created 
23c70 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  using sqlite3_op
23c80 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55  en16() will be U
23c90 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
23ca0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
23cb0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
23cc0 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
23cd0 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
23ce0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
23cf0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
23d00 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
23d10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
23d20 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
23d30 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
23d40 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
23d50 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
23d60 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
23d70 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
23d80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
23d90 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
23da0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
23db0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
23dc0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
23dd0 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
23de0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
23df0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
23e00 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
23e10 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
23e20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
23e30 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
23e40 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
23e50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
23e60 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
23e70 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
23e80 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
23e90 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
23ea0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
23eb0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
23ec0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
23ed0 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
23ee0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
23ef0 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
23f00 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
23f10 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
23f20 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
23f30 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
23f40 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
23f50 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
23f60 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
23f70 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
23f80 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
23f90 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
23fa0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
23fb0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
23fc0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
23fd0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
23fe0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
23ff0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24000 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
24010 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
24020 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
24030 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
24040 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
24050 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
24060 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
24070 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
24080 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
24090 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
240a0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
240b0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
240c0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
240d0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
240e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
240f0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
24100 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
24110 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
24120 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
24130 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24140 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24150 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
24160 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
24170 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
24180 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
24190 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
241a0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
241b0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
241c0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
241d0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
241e0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
241f0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
24200 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
24210 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
24220 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24230 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
24240 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
24250 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
24260 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
24270 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
24280 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
24290 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
242a0 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
242b0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
242c0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
242d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
242e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
242f0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
24300 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
24310 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
24320 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
24330 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
24340 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
24350 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
24360 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
24370 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
24380 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
24390 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
243a0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
243b0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
243c0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
243d0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
243e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
243f0 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
24400 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
24410 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
24420 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
24430 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
24440 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
24450 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
24460 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
24470 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
24480 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
24490 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
244a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
244b0 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
244c0 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
244d0 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
244e0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
244f0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
24500 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
24510 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
24520 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
24530 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
24540 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
24550 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
24560 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
24570 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24580 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
24590 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
245a0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
245b0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
245c0 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
245d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
245e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
245f0 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
24600 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
24610 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
24620 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
24630 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
24640 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
24650 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
24660 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24670 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
24680 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
24690 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
246a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
246b0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
246c0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
246d0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
246e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
246f0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
24700 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
24710 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
24720 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
24730 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
24740 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
24750 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
24760 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
24770 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
24780 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
24790 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
247a0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
247b0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
247c0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
247d0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
247e0 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
247f0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
24800 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
24810 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
24820 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
24830 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
24840 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
24850 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
24860 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
24870 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
24880 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
24890 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
248a0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
248b0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
248c0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
248d0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
248e0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
248f0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
24900 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
24910 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
24920 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
24930 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
24940 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
24950 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
24960 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
24970 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
24980 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
24990 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
249a0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
249b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
249c0 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
249d0 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
249e0 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
249f0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
24a00 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
24a10 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
24a20 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
24a30 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
24a40 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
24a50 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
24a60 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
24a70 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
24a80 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
24a90 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
24aa0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
24ab0 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
24ac0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
24ad0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
24ae0 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
24af0 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
24b00 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
24b10 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
24b20 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
24b30 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
24b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
24b50 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
24b60 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
24b70 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
24b80 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
24b90 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
24ba0 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
24bb0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
24bc0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
24bd0 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
24be0 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
24bf0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
24c00 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
24c10 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
24c20 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
24c30 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
24c40 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
24c50 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
24c60 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
24c70 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
24c80 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
24c90 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
24ca0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
24cb0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
24cc0 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
24cd0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
24ce0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
24cf0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
24d00 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
24d10 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
24d20 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
24d30 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
24d40 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
24d50 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
24d60 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
24d70 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
24d80 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
24d90 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
24da0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
24db0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
24dc0 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
24dd0 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
24de0 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
24df0 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
24e00 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
24e10 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
24e20 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
24e30 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
24e40 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
24e50 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
24e60 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
24e70 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
24e80 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
24e90 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
24ea0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
24eb0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
24ec0 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
24ed0 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
24ee0 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
24ef0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
24f00 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
24f10 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
24f20 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
24f30 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
24f40 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
24f50 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
24f60 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
24f70 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
24f80 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
24f90 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
24fa0 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
24fb0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
24fc0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
24fd0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
24fe0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
24ff0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
25000 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
25010 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
25020 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
25030 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
25040 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
25050 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
25060 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
25070 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
25080 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
25090 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
250a0 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
250b0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
250c0 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
250d0 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
250e0 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
250f0 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
25100 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
25110 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
25120 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
25130 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
25140 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
25150 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
25160 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
25170 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
25180 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
25190 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
251a0 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
251b0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
251c0 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
251d0 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
251e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
251f0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
25200 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
25210 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
25220 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
25230 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
25240 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
25250 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
25260 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
25270 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
25280 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
25290 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
252a0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
252b0 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
252c0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
252d0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
252e0 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
252f0 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
25300 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
25310 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
25320 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
25330 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
25340 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
25350 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
25360 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
25370 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
25380 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
25390 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
253a0 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
253b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
253c0 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
253d0 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
253e0 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
253f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
25400 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
25410 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
25420 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
25430 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
25440 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25450 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
25460 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
25470 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
25480 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
25490 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
254a0 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
254b0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
254c0 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
254d0 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
254e0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
254f0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
25500 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
25510 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
25520 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
25530 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
25540 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
25550 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
25560 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
25570 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
25580 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
25590 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
255a0 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
255b0 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
255c0 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
255d0 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
255e0 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
255f0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
25600 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
25610 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
25620 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
25630 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
25640 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
25650 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
25660 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
25670 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
25680 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
25690 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
256a0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
256b0 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
256c0 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
256d0 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
256e0 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
256f0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
25700 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
25710 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
25720 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
25730 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
25740 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
25750 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
25760 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
25770 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
25780 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
25790 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
257a0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
257b0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
257c0 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
257d0 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
257e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
257f0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
25800 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
25810 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
25820 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
25830 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
25840 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
25850 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
25860 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
25870 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
25880 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
25890 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
258a0 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
258b0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
258c0 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
258d0 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
258e0 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
258f0 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
25900 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
25910 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
25920 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
25930 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
25940 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
25950 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
25960 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
25970 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
25980 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
25990 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
259a0 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
259b0 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
259c0 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
259d0 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
259e0 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
259f0 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
25a00 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
25a10 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
25a20 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
25a30 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
25a40 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
25a50 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
25a60 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
25a70 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
25a80 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
25a90 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
25aa0 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
25ab0 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
25ac0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
25ad0 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
25ae0 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
25af0 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
25b00 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
25b10 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
25b20 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
25b30 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
25b40 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
25b50 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
25b60 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
25b70 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
25b80 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
25b90 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
25ba0 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
25bb0 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
25bc0 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
25bd0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
25be0 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
25bf0 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
25c00 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
25c10 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
25c20 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
25c30 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
25c40 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
25c50 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
25c60 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
25c70 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
25c80 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
25c90 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
25ca0 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
25cb0 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
25cc0 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
25cd0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
25ce0 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
25cf0 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
25d00 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
25d10 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
25d20 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
25d30 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
25d40 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
25d50 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
25d60 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
25d70 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
25d80 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
25d90 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
25da0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
25db0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
25dc0 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
25dd0 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
25de0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
25df0 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
25e00 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
25e10 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
25e20 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
25e30 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
25e40 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
25e50 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
25e60 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
25e70 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
25e80 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
25e90 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
25ea0 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
25eb0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
25ec0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
25ed0 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
25ee0 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
25ef0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
25f00 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
25f10 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
25f20 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
25f30 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
25f40 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
25f50 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
25f60 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
25f70 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
25f80 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
25f90 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
25fa0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
25fb0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
25fc0 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
25fd0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
25fe0 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
25ff0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
26000 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26010 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
26020 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
26030 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
26040 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
26050 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
26060 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
26070 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
26080 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
26090 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
260a0 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
260b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
260c0 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
260d0 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
260e0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
260f0 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
26100 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
26110 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
26120 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
26130 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
26140 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
26150 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
26160 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
26170 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
26180 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
26190 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
261a0 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
261b0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
261c0 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
261d0 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
261e0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
261f0 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
26200 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
26210 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
26220 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
26230 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
26240 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
26250 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
26260 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
26270 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
26280 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
26290 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
262a0 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
262b0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
262c0 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
262d0 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
262e0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
262f0 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
26300 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
26310 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
26320 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26330 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
26340 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
26350 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
26360 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26370 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
26380 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
26390 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
263a0 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
263b0 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
263c0 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
263d0 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
263e0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
263f0 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
26400 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26410 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
26420 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
26430 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
26440 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
26450 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
26460 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
26470 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
26480 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
26490 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
264a0 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
264b0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
264c0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
264d0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
264e0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
264f0 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
26500 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
26510 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
26520 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
26530 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
26540 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
26550 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
26560 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
26570 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
26580 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
26590 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
265a0 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
265b0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
265c0 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
265d0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
265e0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
265f0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
26600 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
26610 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
26620 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
26630 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
26640 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
26650 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
26660 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
26670 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
26680 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
26690 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
266a0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
266b0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
266c0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
266d0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
266e0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
266f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26700 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
26710 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
26720 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
26730 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
26740 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
26750 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
26760 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
26770 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
26780 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
26790 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
267a0 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
267b0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
267c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
267d0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
267e0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
267f0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
26800 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
26810 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
26820 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
26830 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
26840 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
26850 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
26860 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
26870 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
26880 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
26890 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
268a0 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
268b0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
268c0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
268d0 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ry].*/.int sqlit
268e0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
268f0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
26900 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
26910 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
26920 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
26930 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
26940 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
26950 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
26960 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
26970 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
26980 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
26990 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
269a0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
269b0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
269c0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
269d0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
269e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
269f0 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
26a00 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
26a10 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
26a20 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
26a30 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
26a40 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
26a50 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
26a60 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
26a70 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
26a80 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
26a90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
26aa0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
26ab0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
26ac0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
26ad0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
26ae0 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
26af0 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
26b00 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
26b10 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
26b20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
26b30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
26b40 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
26b50 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
26b60 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
26b70 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
26b80 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
26b90 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
26ba0 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
26bb0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
26bc0 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
26bd0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
26be0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
26bf0 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
26c00 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
26c10 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
26c20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
26c30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
26c40 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
26c50 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
26c60 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
26c70 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
26c80 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
26c90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
26ca0 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
26cb0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
26cc0 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
26cd0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
26ce0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
26cf0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
26d00 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
26d10 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
26d20 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
26d30 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
26d40 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
26d50 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
26d60 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
26d70 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
26d80 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
26d90 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
26da0 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
26db0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
26dc0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
26dd0 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
26de0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
26df0 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
26e00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
26e10 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
26e20 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
26e30 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
26e40 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
26e50 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
26e60 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
26e70 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
26e80 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
26e90 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
26ea0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
26eb0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
26ec0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
26ed0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
26ee0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26ef0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
26f00 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
26f10 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
26f20 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
26f30 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
26f40 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
26f50 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
26f60 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
26f70 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
26f80 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
26f90 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
26fa0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
26fb0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
26fc0 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
26fd0 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
26fe0 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
26ff0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
27000 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
27010 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
27020 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
27030 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
27040 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
27050 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
27060 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
27070 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
27080 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27090 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
270a0 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
270b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
270c0 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
270d0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
270e0 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
270f0 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
27100 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
27110 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
27120 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
27130 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
27140 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
27150 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
27160 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
27170 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
27180 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
27190 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
271a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
271b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
271c0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
271d0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
271e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
271f0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27200 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
27210 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
27220 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
27230 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
27240 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
27250 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
27260 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
27270 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
27280 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
27290 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
272a0 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
272b0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
272c0 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
272d0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
272e0 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
272f0 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
27300 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
27310 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
27320 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  );.int sqlite3_u
27330 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
27340 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
27350 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
27360 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
27370 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
27380 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
27390 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
273a0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
273b0 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
273c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
273d0 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
273e0 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  sages.** METHOD:
273f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
27400 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
27410 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  nt sqlite3_* API
27420 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
27430 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62   with .** [datab
27440 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
27450 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74  D failed, then t
27460 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
27470 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a  de(D) interface.
27480 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ** returns the n
27490 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
274a0 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
274b0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
274c0 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63  or that.** API c
274d0 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d  all..** If the m
274e0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
274f0 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66  all was successf
27500 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ul,.** then the 
27510 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
27520 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  m sqlite3_errcod
27530 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
27540 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
27550 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
27560 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
27570 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
27580 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
27590 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
275a0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
275b0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
275c0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
275d0 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
275e0 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
275f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
27600 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
27610 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
27620 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
27630 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
27640 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
27650 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
27660 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
27670 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
27680 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
27690 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
276a0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
276b0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
276c0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
276d0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
276e0 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
276f0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
27700 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
27710 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
27720 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
27730 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
27740 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
27750 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
27760 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
27770 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
27780 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
27790 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
277a0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
277b0 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
277c0 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
277d0 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
277e0 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
277f0 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
27800 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
27810 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
27820 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
27830 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
27840 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
27850 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
27860 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
27870 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
27880 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
27890 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
278a0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
278b0 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
278c0 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
278d0 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
278e0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
278f0 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
27900 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
27910 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
27920 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
27930 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
27940 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
27950 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
27960 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
27970 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
27980 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
27990 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
279a0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
279b0 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
279c0 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
279d0 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
279e0 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
279f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
27a00 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
27a10 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
27a20 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
27a30 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
27a40 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
27a50 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
27a60 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
27a70 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
27a80 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
27a90 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
27aa0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
27ab0 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
27ac0 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
27ad0 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
27ae0 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
27af0 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
27b00 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
27b10 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
27b20 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
27b30 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
27b40 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
27b50 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
27b60 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
27b70 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
27b80 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
27b90 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20   be set..*/.int 
27ba0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
27bb0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
27bc0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
27bd0 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
27be0 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
27bf0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
27c00 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
27c10 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
27c20 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
27c30 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61  te3*);.const cha
27c40 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74  r *sqlite3_errst
27c50 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
27c60 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
27c70 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
27c80 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
27c90 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
27ca0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
27cb0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
27cc0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
27cd0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
27ce0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
27cf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
27d00 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63  at.** has been c
27d10 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e  ompiled into bin
27d20 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20  ary form and is 
27d30 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c  ready to be eval
27d40 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  uated..**.** Thi
27d50 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73  nk of each SQL s
27d60 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65  tatement as a se
27d70 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20  parate computer 
27d80 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a  program.  The.**
27d90 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
27da0 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64  xt is source cod
27db0 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73  e.  A prepared s
27dc0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
27dd0 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69  .** is the compi
27de0 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e  led object code.
27df0 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62    All SQL must b
27e00 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  e converted into
27e10 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73   a.** prepared s
27e20 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20  tatement before 
27e30 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a  it can be run..*
27e40 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79  *.** The life-cy
27e50 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  cle of a prepare
27e60 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
27e70 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20  ct usually goes 
27e80 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
27e90 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
27ea0 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65  eate the prepare
27eb0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
27ec0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
27ed0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e  3_prepare_v2()].
27ee0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
27ef0 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74  lues to [paramet
27f00 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
27f10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
27f20 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
27f30 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
27f40 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
27f50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
27f60 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
27f70 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
27f80 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
27f90 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
27fa0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
27fb0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
27fc0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
27fd0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
27fe0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
27ff0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
28000 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
28010 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
28020 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
28030 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
28040 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
28050 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
28060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28070 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
28080 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
28090 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  3.**.** ^(This i
280a0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
280b0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
280c0 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
280d0 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
280e0 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
280f0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
28100 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
28110 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
28120 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
28130 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
28140 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
28150 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
28160 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
28170 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
28180 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
28190 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
281a0 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
281b0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
281c0 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
281d0 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
281e0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
281f0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
28200 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
28210 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
28220 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
28230 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
28240 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
28250 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
28260 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
28270 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
28280 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
28290 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
282a0 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
282b0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
282c0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
282d0 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
282e0 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
282f0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
28300 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
28310 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
28320 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
28330 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
28340 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
28350 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
28360 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
28370 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
28380 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
28390 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
283a0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
283b0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
283c0 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
283d0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
283e0 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
283f0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
28400 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
28410 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
28420 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
28430 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
28440 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
28450 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
28460 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
28470 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
28480 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
28490 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
284a0 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
284b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
284c0 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
284d0 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
284e0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
284f0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
28500 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
28510 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
28520 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
28530 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
28540 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
28550 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
28560 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
28570 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
28580 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
28590 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
285a0 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
285b0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
285c0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
285d0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
285e0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
285f0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
28600 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
28610 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
28620 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
28630 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
28640 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
28650 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
28660 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
28670 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
28680 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
28690 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
286a0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
286b0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
286c0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
286d0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
286e0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
286f0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
28700 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
28710 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
28720 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
28730 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
28740 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
28750 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
28760 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
28770 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
28780 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
28790 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
287a0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
287b0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
287c0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
287d0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
287e0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
287f0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
28800 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
28810 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
28820 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
28830 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
28840 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
28850 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
28860 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28870 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
28880 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
28890 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
288a0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
288b0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
288c0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
288d0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
288e0 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
288f0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
28900 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
28910 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
28920 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
28930 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
28940 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
28950 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
28960 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
28970 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
28980 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
28990 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
289a0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
289b0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
289c0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
289d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
289e0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
289f0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
28a00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
28a10 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
28a20 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
28a30 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
28a40 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
28a50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28a60 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
28a70 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
28a80 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
28a90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28aa0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28ab0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
28ac0 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
28ad0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
28ae0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
28af0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28b00 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
28b10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28b20 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
28b30 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
28b40 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
28b50 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
28b60 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
28b70 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
28b80 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
28b90 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
28ba0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
28bb0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
28bc0 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
28bd0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28be0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
28bf0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
28c00 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
28c10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28c20 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
28c30 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
28c40 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
28c50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
28c60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
28c70 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
28c80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28c90 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
28ca0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
28cb0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
28cc0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
28cd0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
28ce0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
28cf0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
28d00 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
28d10 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
28d20 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
28d30 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28d40 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
28d50 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
28d60 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
28d70 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
28d80 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
28d90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
28da0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
28db0 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
28dc0 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
28dd0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
28de0 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
28df0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
28e00 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
28e10 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28e20 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
28e30 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
28e40 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
28e50 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
28e60 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
28e70 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
28e80 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
28e90 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
28ea0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
28eb0 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
28ec0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
28ed0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
28ee0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
28ef0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
28f00 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
28f10 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
28f20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
28f30 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
28f40 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
28f50 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
28f60 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
28f70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28f80 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28f90 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
28fa0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
28fb0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
28fc0 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
28fd0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
28fe0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
28ff0 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
29000 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29010 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
29020 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29030 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
29040 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
29050 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
29060 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
29070 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29080 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
29090 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
290a0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
290b0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
290c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
290d0 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
290e0 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
290f0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29100 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
29110 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
29120 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
29130 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
29140 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29150 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
29160 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
29170 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
29180 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
29190 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
291a0 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
291b0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
291c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
291d0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
291e0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
291f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29200 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
29210 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
29220 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29230 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
29240 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
29250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29260 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
29270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
29280 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29290 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
292a0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
292b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
292c0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
292d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
292e0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
292f0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
29300 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
29310 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
29320 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
29330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29340 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
29350 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
29360 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
29370 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
29380 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
29390 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
293a0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
293b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
293c0 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
293d0 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
293e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
293f0 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
29400 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
29410 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
29420 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
29430 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
29440 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
29450 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54  compiler}.** MET
29460 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20  HOD: sqlite3.** 
29470 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
29480 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
29490 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
294a0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
294b0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
294c0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
294d0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
294e0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
294f0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
29500 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
29510 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
29520 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29530 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
29540 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
29550 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
29560 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
29570 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
29580 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
29590 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
295a0 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
295b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
295c0 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
295d0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
295e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
295f0 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
29600 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
29610 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
29620 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
29630 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
29640 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
29650 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
29660 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
29670 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
29680 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
29690 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
296a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
296b0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
296c0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
296d0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
296e0 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61  argument is nega
296f0 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20  tive, then zSql 
29700 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
29710 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
29720 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
29730 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76  nByte is positiv
29740 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
29750 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
29760 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
29770 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20  Sql.  ^If nByte 
29780 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f  is zero, then no
29790 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
297a0 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61  tement is genera
297b0 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ted..** If the c
297c0 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74  aller knows that
297d0 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
297e0 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
297f0 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  inated, then.** 
29800 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
29810 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
29820 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e  antage to passin
29830 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
29840 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
29850 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
29860 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
29870 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
29880 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
29890 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  nul-terminator..
298a0 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
298b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
298c0 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
298d0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
298e0 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
298f0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
29900 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
29910 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
29920 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
29930 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
29940 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
29950 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
29960 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
29970 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
29980 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
29990 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
299a0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
299b0 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
299c0 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
299d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
299e0 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
299f0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
29a00 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
29a10 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
29a20 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
29a30 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
29a40 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
29a50 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
29a60 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
29a70 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
29a80 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
29a90 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
29aa0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
29ab0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
29ac0 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
29ad0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
29ae0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
29af0 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
29b00 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
29b10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
29b20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
29b30 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
29b40 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
29b50 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
29b60 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
29b70 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29b80 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
29b90 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
29ba0 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
29bb0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
29bc0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
29bd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
29be0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
29bf0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
29c00 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
29c10 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
29c20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
29c30 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
29c40 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
29c50 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
29c60 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
29c70 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
29c80 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
29c90 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
29ca0 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
29cb0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
29cc0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
29cd0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
29ce0 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
29cf0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
29d00 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
29d10 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
29d20 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
29d30 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
29d40 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
29d50 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
29d60 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
29d70 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
29d80 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
29d90 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
29da0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
29db0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
29dc0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
29dd0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
29de0 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
29df0 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
29e00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29e10 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
29e20 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
29e30 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
29e40 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
29e50 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20  un it again. As 
29e60 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f  many as [SQLITE_
29e70 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59  MAX_SCHEMA_RETRY
29e80 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c  ].** retries wil
29e90 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73  l occur before s
29ea0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69  qlite3_step() gi
29eb0 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72  ves up and retur
29ec0 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20  ns an error..** 
29ed0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
29ee0 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
29ef0 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
29f00 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
29f10 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
29f20 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
29f30 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
29f40 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
29f50 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
29f60 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
29f70 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
29f80 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
29f90 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
29fa0 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
29fb0 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
29fc0 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
29fd0 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
29fe0 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
29ff0 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
2a000 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
2a010 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
2a020 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
2a030 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
2a040 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
2a050 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
2a060 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2a070 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
2a080 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
2a090 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
2a0a0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
2a0b0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
2a0c0 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
2a0d0 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
2a0e0 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
2a0f0 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
2a100 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
2a110 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
2a120 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
2a130 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
2a140 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
2a150 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
2a160 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
2a170 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
2a180 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
2a190 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
2a1a0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
2a1b0 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
2a1c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a1d0 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
2a1e0 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
2a1f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2a200 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
2a210 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
2a220 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
2a230 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
2a240 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
2a250 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
2a260 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
2a270 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
2a280 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
2a290 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2a2a0 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
2a2b0 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
2a2c0 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
2a2d0 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
2a2e0 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
2a2f0 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
2a300 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
2a310 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
2a320 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
2a330 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
2a340 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69  enabled..** </li
2a350 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e  >.** </ol>.*/.in
2a360 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2a370 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2a380 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2a390 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2a3a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2a3b0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2a3c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2a3d0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2a3e0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2a3f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2a400 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2a410 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2a420 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2a430 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2a440 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2a450 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2a460 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2a470 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2a480 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2a490 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2a4a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2a4b0 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
2a4c0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2a4d0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2a4e0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a4f0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2a500 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2a510 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2a520 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2a530 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2a540 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2a550 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2a560 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2a570 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2a580 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2a590 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2a5a0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2a5b0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2a5c0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2a5d0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2a5e0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2a5f0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
2a600 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2a610 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2a620 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2a630 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2a640 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2a650 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2a660 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2a670 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2a680 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2a690 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2a6a0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2a6b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2a6c0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2a6d0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2a6e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2a6f0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2a700 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2a710 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2a720 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2a730 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2a740 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
2a750 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2a760 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2a770 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2a780 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2a790 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2a7a0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2a7b0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2a7c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2a7d0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2a7e0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2a7f0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2a800 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2a810 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2a820 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2a830 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2a840 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2a850 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2a860 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2a870 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
2a880 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
2a890 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
2a8a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2a8b0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2a8c0 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50  he sqlite3_sql(P
2a8d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2a8e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2a8f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55   a copy of the U
2a900 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74  TF-8.** SQL text
2a910 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
2a920 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a930 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a  ent] P if P was.
2a940 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 65 69  ** created by ei
2a950 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
2a960 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2a970 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a980 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  6_v2()]..** ^The
2a990 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2a9a0 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  d_sql(P) interfa
2a9b0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2a9c0 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a  nter to a UTF-8.
2a9d0 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
2a9e0 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78  ning the SQL tex
2a9f0 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74  t of prepared st
2aa00 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a  atement P with.*
2aa10 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  * [bound paramet
2aa20 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a  ers] expanded..*
2aa30 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2aa40 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65  le, if a prepare
2aa50 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
2aa60 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
2aa70 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45   SQL.** text "SE
2aa80 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2aa90 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72  and if parameter
2aaa0 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74   $abc is bound t
2aab0 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a  o integer 2345.*
2aac0 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * and parameter 
2aad0 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c  :xyz is unbound,
2aae0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71   then sqlite3_sq
2aaf0 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  l() will return.
2ab00 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
2ab10 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20  string, "SELECT 
2ab20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73  $abc,:xyz" but s
2ab30 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2ab40 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  sql().** will re
2ab50 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34  turn "SELECT 234
2ab60 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a  5,NULL".)^.**.**
2ab70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2ab80 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74  panded_sql() int
2ab90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e  erface returns N
2aba0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
2abb0 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73  ent memory.** is
2abc0 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f   available to ho
2abd0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f  ld the result, o
2abe0 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20  r if the result 
2abf0 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
2ac00 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  .** the maximum 
2ac10 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65  string length de
2ac20 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
2ac30 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2ac40 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  NGTH]..**.** ^Th
2ac50 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
2ac60 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
2ac70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2ac80 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20  limits the size 
2ac90 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61  of.** bound para
2aca0 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73  meter expansions
2acb0 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
2acc0 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70  OMIT_TRACE] comp
2acd0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
2ace0 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65  on causes sqlite
2acf0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2ad00 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72   to always retur
2ad10 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  n NULL..**.** ^T
2ad20 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2ad30 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71  ed by sqlite3_sq
2ad40 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20  l(P) is managed 
2ad50 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73  by SQLite and is
2ad60 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
2ad70 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65  y freed when the
2ad80 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ad90 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2ada0 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67  ..** ^The string
2adb0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2adc0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2add0 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68  l(P), on the oth
2ade0 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f  er hand,.** is o
2adf0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2ae00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
2ae10 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65  and must be free
2ae20 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
2ae30 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e  ion.** by passin
2ae40 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
2ae50 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  _free()]..*/.con
2ae60 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2ae70 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2ae80 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20  t *pStmt);.char 
2ae90 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  *sqlite3_expande
2aea0 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  d_sql(sqlite3_st
2aeb0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2aec0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2aed0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
2aee0 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
2aef0 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
2af00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2af10 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2af20 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2af30 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
2af40 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2af50 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a  e (non-zero) if.
2af60 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  ** and only if t
2af70 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2af80 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20  tement] X makes 
2af90 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65  no direct change
2afa0 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  s to.** the cont
2afb0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2afc0 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
2afd0 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69  Note that [appli
2afe0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2aff0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
2b000 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
2b010 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67  les] might chang
2b020 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
2b030 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73  ndirectly as a s
2b040 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a  ide effect.  .**
2b050 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2b060 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
2b070 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63  n defines a func
2b080 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68  tion "eval()" th
2b090 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71  at .** calls [sq
2b0a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74  lite3_exec()], t
2b0b0 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  hen the followin
2b0c0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  g SQL statement 
2b0d0 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20  would.** change 
2b0e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2b0f0 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65  e through side-e
2b100 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ffects:.**.** <b
2b110 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2b120 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61  **    SELECT eva
2b130 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  l('DELETE FROM t
2b140 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20  1') FROM t2;.** 
2b150 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
2b160 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65  te>.**.** But be
2b170 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43  cause the [SELEC
2b180 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  T] statement doe
2b190 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2b1a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
2b1b0 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69  * directly, sqli
2b1c0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2b1d0 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20  y() would still 
2b1e0 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a  return true.)^.*
2b1f0 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f  *.** ^Transactio
2b200 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d  n control statem
2b210 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45  ents such as [BE
2b220 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20  GIN], [COMMIT], 
2b230 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b  [ROLLBACK],.** [
2b240 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20  SAVEPOINT], and 
2b250 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20  [RELEASE] cause 
2b260 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2b270 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2b280 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65  n true,.** since
2b290 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
2b2a0 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
2b2b0 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  t actually modif
2b2c0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  y the database b
2b2d0 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65  ut.** rather the
2b2e0 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69  y control the ti
2b2f0 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68  ming of when oth
2b300 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f  er statements mo
2b310 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74  dify the .** dat
2b320 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54  abase.  ^The [AT
2b330 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43  TACH] and [DETAC
2b340 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c  H] statements al
2b350 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69  so cause.** sqli
2b360 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2b370 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
2b380 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20  ue since, while 
2b390 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73  those statements
2b3a0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63  .** change the c
2b3b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20  onfiguration of 
2b3c0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
2b3d0 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e  ction, they do n
2b3e0 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e  ot make .** chan
2b3f0 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65  ges to the conte
2b400 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2b410 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b  se files on disk
2b420 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2b430 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
2b440 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2b450 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2b460 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2b470 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
2b480 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
2b490 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44   Reset.** METHOD
2b4a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2b4b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b4c0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
2b4d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2b4e0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2b4f0 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
2b500 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b510 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
2b520 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
2b530 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2b540 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
2b550 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e   has neither run
2b560 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28   to completion (
2b570 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2b580 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b  ITE_DONE] from [
2b590 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2b5a0 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65  ) nor.** been re
2b5b0 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
2b5c0 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
2b5d0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2b5e0 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
2b5f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
2b600 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
2b610 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
2b620 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
2b630 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
2b640 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
2b650 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
2b660 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b670 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
2b680 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2b690 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2b6a0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
2b6b0 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
2b6c0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2b6d0 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
2b6e0 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
2b6f0 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
2b700 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
2b710 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
2b720 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2b730 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
2b740 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
2b750 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
2b760 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
2b770 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
2b780 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
2b790 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
2b7a0 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
2b7b0 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
2b7c0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
2b7d0 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
2b7e0 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
2b7f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2b800 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
2b810 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2b820 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
2b830 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
2b840 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
2b850 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
2b860 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
2b870 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
2b880 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
2b890 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2b8a0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2b8b0 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
2b8c0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
2b8d0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
2b8e0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
2b8f0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
2b900 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
2b910 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
2b920 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
2b930 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
2b940 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
2b950 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
2b960 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
2b970 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2b980 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
2b990 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
2b9a0 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
2b9b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
2b9c0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
2b9d0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
2b9e0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
2b9f0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2ba00 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
2ba10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2ba20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
2ba30 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
2ba40 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
2ba50 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
2ba60 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ba70 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
2ba80 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
2ba90 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
2baa0 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
2bab0 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
2bac0 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
2bad0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
2bae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2baf0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
2bb00 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74  value_dup()] int
2bb10 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2bb20 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20  ed to construct 
2bb30 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63  a new .** protec
2bb40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bb50 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74  e from an unprot
2bb60 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2bb70 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
2bb80 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
2bb90 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
2bba0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
2bbb0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
2bbc0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
2bbd0 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
2bbe0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
2bbf0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2bc00 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2bc10 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
2bc20 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
2bc30 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2bc40 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2bc50 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
2bc60 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
2bc70 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
2bc80 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
2bc90 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
2bca0 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
2bcb0 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
2bcc0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
2bcd0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
2bce0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
2bcf0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
2bd00 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
2bd10 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2bd20 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
2bd30 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
2bd40 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
2bd50 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
2bd60 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2bd70 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2bd80 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2bd90 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
2bda0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
2bdb0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
2bdc0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
2bdd0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
2bde0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
2bdf0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
2be00 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
2be10 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
2be20 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
2be30 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2be40 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2be50 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2be60 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
2be70 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
2be80 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2be90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2bea0 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
2beb0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
2bec0 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
2bed0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
2bee0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
2bef0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2bf00 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
2bf10 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
2bf20 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2bf30 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2bf40 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2bf50 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2bf60 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
2bf70 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
2bf80 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2bf90 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
2bfa0 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
2bfb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2bfc0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2bfd0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2bfe0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
2bff0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
2c000 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2c010 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
2c020 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
2c030 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
2c040 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c050 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
2c060 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
2c070 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
2c080 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
2c090 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2c0a0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2c0b0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
2c0c0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
2c0d0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
2c0e0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
2c0f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2c100 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
2c110 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
2c120 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
2c130 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
2c140 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
2c150 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2c160 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c170 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
2c180 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c190 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2c1a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
2c1b0 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
2c1c0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
2c1d0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
2c1e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
2c1f0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
2c200 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2c210 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2c220 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
2c230 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
2c240 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2c250 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
2c260 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
2c270 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
2c280 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
2c290 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
2c2a0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2c2b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
2c2c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
2c2d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c2e0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
2c2f0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
2c300 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
2c310 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
2c320 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
2c330 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
2c340 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
2c350 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
2c360 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
2c370 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
2c380 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
2c390 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2c3a0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  _stmt.**.** ^(In
2c3b0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2c3c0 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
2c3d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c3e0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
2c3f0 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
2c400 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
2c410 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
2c420 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
2c430 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
2c440 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
2c450 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2c460 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
2c470 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
2c480 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
2c490 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
2c4a0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2c4b0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
2c4c0 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
2c4d0 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
2c4e0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
2c4f0 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
2c500 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
2c510 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
2c520 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
2c530 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
2c540 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
2c550 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
2c560 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
2c570 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
2c580 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
2c590 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2c5a0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
2c5b0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
2c5c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2c5d0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
2c5e0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2c5f0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
2c600 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2c610 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2c620 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
2c630 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
2c640 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2c650 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
2c660 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
2c670 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2c680 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2c690 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
2c6a0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
2c6b0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
2c6c0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2c6d0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
2c6e0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
2c6f0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
2c700 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
2c710 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
2c720 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2c730 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
2c740 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
2c750 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
2c760 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
2c770 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
2c780 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2c790 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
2c7a0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
2c7b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2c7c0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2c7d0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
2c7e0 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
2c7f0 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
2c800 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
2c810 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
2c820 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
2c830 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
2c840 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
2c850 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
2c860 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
2c870 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2c880 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
2c890 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
2c8a0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
2c8b0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
2c8c0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
2c8d0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
2c8e0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2c8f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2c900 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2c910 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2c920 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
2c930 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2c940 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2c950 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
2c960 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
2c970 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
2c980 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
2c990 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
2c9a0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
2c9b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
2c9c0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
2c9d0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
2c9e0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
2c9f0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2ca00 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2ca10 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
2ca20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
2ca30 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2ca40 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
2ca50 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
2ca60 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
2ca70 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2ca80 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
2ca90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2caa0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2cab0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2cac0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2cad0 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
2cae0 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
2caf0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
2cb00 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
2cb10 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
2cb20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
2cb30 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
2cb40 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2cb50 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2cb60 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2cb70 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
2cb80 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
2cb90 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2cba0 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
2cbb0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2cbc0 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
2cbd0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2cbe0 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
2cbf0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2cc00 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2cc10 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
2cc20 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
2cc30 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2cc40 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2cc50 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2cc60 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2cc70 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2cc80 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2cc90 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2cca0 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2ccb0 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2ccc0 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2ccd0 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2cce0 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2ccf0 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2cd00 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2cd10 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2cd20 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2cd30 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2cd40 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2cd50 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2cd60 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2cd70 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2cd80 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2cd90 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2cda0 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
2cdb0 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
2cdc0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
2cdd0 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
2cde0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
2cdf0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2ce00 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
2ce10 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
2ce20 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
2ce30 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2ce40 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
2ce50 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2ce60 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
2ce70 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
2ce80 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
2ce90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2cea0 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
2ceb0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
2cec0 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
2ced0 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
2cee0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2cef0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
2cf00 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
2cf10 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
2cf20 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
2cf30 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
2cf40 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2cf50 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
2cf60 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
2cf70 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
2cf80 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
2cf90 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2cfa0 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
2cfb0 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
2cfc0 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
2cfd0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2cfe0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
2cff0 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
2d000 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2d010 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
2d020 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
2d030 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2d040 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2d050 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2d060 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2d070 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
2d080 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
2d090 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
2d0a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2d0b0 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
2d0c0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2d0d0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2d0e0 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
2d0f0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
2d100 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
2d110 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
2d120 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2d130 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
2d140 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
2d150 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
2d160 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
2d170 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
2d180 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
2d190 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2d1a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2d1b0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2d1c0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2d1d0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2d1e0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2d1f0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2d200 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2d210 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2d220 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2d230 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2d240 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2d250 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2d260 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2d270 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2d280 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2d290 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2d2a0 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2d2b0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2d2c0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2d2d0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2d2e0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2d2f0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2d300 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2d310 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2d320 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2d330 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2d340 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2d350 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
2d360 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2d370 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2d380 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2d390 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2d3a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2d3b0 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2d3c0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2d3d0 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2d3e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2d3f0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2d400 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2d410 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2d420 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2d430 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2d440 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2d450 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2d460 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2d470 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
2d480 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
2d490 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2d4a0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2d4b0 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
2d4c0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
2d4d0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
2d4e0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
2d4f0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
2d500 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
2d510 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
2d520 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
2d530 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
2d540 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
2d550 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
2d560 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2d570 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
2d580 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2d590 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
2d5a0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
2d5b0 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
2d5c0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
2d5d0 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74  TE_TOOBIG] might
2d5e0 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
2d5f0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74  the size of a st
2d600 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20  ring or BLOB.** 
2d610 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69  exceeds limits i
2d620 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  mposed by [sqlit
2d630 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2d640 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29  E_LIMIT_LENGTH])
2d650 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d   or.** [SQLITE_M
2d660 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e  AX_LENGTH]..** ^
2d670 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2d680 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2d690 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2d6a0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2d6b0 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2d6c0 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2d6d0 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2d6e0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2d6f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2d700 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2d710 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
2d720 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2d730 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
2d740 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2d750 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2d760 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2d770 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
2d780 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2d790 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
2d7a0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
2d7b0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2d7c0 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69  bind_blob64(sqli
2d7d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d7e0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c  const void*, sql
2d7f0 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2d800 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d810 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
2d820 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2d830 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
2d840 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d850 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
2d860 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
2d870 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2d880 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
2d890 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
2d8a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d8b0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
2d8c0 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
2d8d0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
2d8e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2d8f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2d900 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2d910 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
2d920 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
2d930 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2d940 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2d950 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d960 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2d970 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2d980 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2d990 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2d9a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2d9b0 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
2d9c0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2d9d0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2d9e0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2d9f0 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
2da00 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
2da10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2da20 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
2da30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2da40 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
2da50 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2da60 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
2da70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2da80 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73  t, int n);.int s
2da90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2daa0 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
2dab0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2dac0 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  e3_uint64);../*.
2dad0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2dae0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
2daf0 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eters.** METHOD:
2db00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2db10 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2db20 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2db30 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
2db40 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
2db50 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
2db60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2db70 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
2db80 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
2db90 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
2dba0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
2dbb0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
2dbc0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
2dbd0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
2dbe0 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
2dbf0 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
2dc00 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
2dc10 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
2dc20 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
2dc30 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
2dc40 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
2dc50 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
2dc60 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
2dc70 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
2dc80 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
2dc90 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
2dca0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
2dcb0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
2dcc0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
2dcd0 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
2dce0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
2dcf0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
2dd00 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
2dd10 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
2dd20 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
2dd30 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
2dd40 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2dd50 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2dd60 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2dd70 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2dd80 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2dd90 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2dda0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2ddb0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2ddc0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ddd0 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
2dde0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2ddf0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2de00 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
2de10 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eter.** METHOD: 
2de20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2de30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2de40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2de50 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
2de60 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
2de70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
2de80 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
2de90 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
2dea0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2deb0 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
2dec0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2ded0 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
2dee0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2def0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
2df00 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
2df10 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
2df20 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2df30 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2df40 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
2df50 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2df60 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
2df70 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
2df80 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
2df90 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
2dfa0 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
2dfb0 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
2dfc0 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
2dfd0 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
2dfe0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
2dff0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
2e000 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
2e010 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
2e020 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
2e030 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
2e040 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
2e050 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2e060 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
2e070 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
2e080 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
2e090 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
2e0a0 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
2e0b0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
2e0c0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
2e0d0 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
2e0e0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
2e0f0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
2e100 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
2e110 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
2e120 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
2e130 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
2e140 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2e150 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e160 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
2e170 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2e180 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2e190 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2e1a0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2e1b0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2e1c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e1d0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2e1e0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2e1f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2e200 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
2e210 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
2e220 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2e230 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2e240 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
2e250 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
2e260 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
2e270 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
2e280 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e290 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
2e2a0 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
2e2b0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
2e2c0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
2e2d0 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
2e2e0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
2e2f0 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
2e300 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
2e310 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
2e320 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
2e330 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2e340 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
2e350 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2e360 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
2e370 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
2e380 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
2e390 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
2e3a0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
2e3b0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
2e3c0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
2e3d0 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
2e3e0 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
2e3f0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2e400 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2e410 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2e420 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2e430 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2e440 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2e450 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e460 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2e470 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2e480 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2e490 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2e4a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e4b0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
2e4c0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
2e4d0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
2e4e0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2e4f0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
2e500 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2e510 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
2e520 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e530 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2e540 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2e550 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2e560 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2e570 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2e580 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2e590 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2e5a0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2e5b0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2e5c0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2e5d0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2e5e0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2e5f0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
2e600 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2e610 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2e620 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e630 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2e640 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2e650 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2e660 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e670 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2e680 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2e690 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2e6a0 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2e6b0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2e6c0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
2e6d0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2e6e0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
2e6f0 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
2e700 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
2e710 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
2e720 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
2e730 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
2e740 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2e750 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2e760 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e770 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
2e780 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2e790 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e7a0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
2e7b0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2e7c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2e7d0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2e7e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2e7f0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
2e800 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
2e810 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
2e820 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
2e830 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2e840 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
2e850 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2e860 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
2e870 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2e880 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2e890 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2e8a0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
2e8b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e8c0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
2e8d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2e8e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2e8f0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
2e900 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
2e910 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2e920 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e930 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
2e940 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
2e950 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
2e960 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2e970 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
2e980 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
2e990 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2e9a0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
2e9b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
2e9c0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
2e9d0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
2e9e0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
2e9f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ea00 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
2ea10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
2ea20 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2ea30 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2ea40 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2ea50 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2ea60 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2ea70 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2ea80 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2ea90 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2eaa0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
2eab0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2eac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2ead0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2eae0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
2eaf0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
2eb00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
2eb10 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
2eb20 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
2eb30 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
2eb40 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
2eb50 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
2eb60 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
2eb70 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
2eb80 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
2eb90 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2eba0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2ebb0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
2ebc0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
2ebd0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
2ebe0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
2ebf0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
2ec00 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
2ec10 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
2ec20 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
2ec30 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
2ec40 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
2ec50 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
2ec60 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
2ec70 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
2ec80 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
2ec90 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
2eca0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2ecb0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
2ecc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ecd0 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
2ece0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ecf0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2ed00 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
2ed10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2ed20 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
2ed30 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2ed40 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2ed50 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2ed60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
2ed70 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
2ed80 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
2ed90 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2eda0 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
2edb0 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
2edc0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
2edd0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
2ede0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
2edf0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
2ee00 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2ee10 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
2ee20 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
2ee30 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
2ee40 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
2ee50 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
2ee60 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
2ee70 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
2ee80 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
2ee90 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
2eea0 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
2eeb0 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
2eec0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
2eed0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
2eee0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2eef0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
2ef00 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2ef10 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
2ef20 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
2ef30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
2ef40 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
2ef50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2ef60 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2ef70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2ef80 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2ef90 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2efa0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2efb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2efc0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2efd0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2efe0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
2eff0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
2f000 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
2f010 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
2f020 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
2f030 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
2f040 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
2f050 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
2f060 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
2f070 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2f080 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
2f090 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2f0a0 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
2f0b0 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
2f0c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f0d0 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
2f0e0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2f0f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2f100 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
2f110 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2f120 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
2f130 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
2f140 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2f150 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2f160 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
2f170 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
2f180 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
2f190 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
2f1a0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2f1b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2f1c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
2f1d0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
2f1e0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
2f1f0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
2f200 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
2f210 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2f220 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
2f230 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
2f240 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
2f250 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
2f260 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2f270 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
2f280 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
2f290 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
2f2a0 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
2f2b0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
2f2c0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
2f2d0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
2f2e0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
2f2f0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
2f300 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
2f310 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
2f320 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
2f330 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
2f340 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
2f350 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
2f360 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
2f370 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
2f380 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
2f390 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
2f3a0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
2f3b0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
2f3c0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
2f3d0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2f3e0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
2f3f0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
2f400 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
2f410 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2f420 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2f430 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2f440 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2f450 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
2f460 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
2f470 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
2f480 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2f490 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2f4a0 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
2f4b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
2f4c0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2f4d0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2f4e0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
2f4f0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2f500 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
2f510 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
2f520 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
2f530 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f540 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
2f550 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
2f560 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2f570 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2f580 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2f590 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2f5a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2f5b0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
2f5c0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2f5d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f5e0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2f5f0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2f600 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2f610 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2f620 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2f630 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2f640 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2f650 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f660 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
2f670 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2f680 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2f690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2f6a0 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2f6b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2f6c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f6d0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2f6e0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2f6f0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2f700 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
2f710 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
2f720 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2f730 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2f740 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  3_stmt.**.** ^(T
2f750 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2f760 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2f770 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2f780 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2f790 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2f7a0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2f7b0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2f7c0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2f7d0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2f7e0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2f7f0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2f800 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2f810 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2f820 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2f830 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2f840 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2f850 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2f860 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2f870 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2f880 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2f890 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2f8a0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2f8b0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2f8c0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2f8d0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2f8e0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2f8f0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2f900 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2f910 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2f920 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2f930 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2f940 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2f950 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2f960 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2f970 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2f980 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2f990 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2f9a0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2f9b0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2f9c0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2f9d0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2f9e0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2f9f0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2fa00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2fa10 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2fa20 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2fa30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2fa40 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2fa50 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2fa60 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2fa70 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2fa80 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2fa90 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2faa0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2fab0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2fac0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2fad0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2fae0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2faf0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2fb00 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2fb10 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2fb20 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2fb30 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2fb40 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2fb50 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2fb60 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2fb70 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2fb80 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2fb90 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2fba0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2fbb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2fbc0 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
2fbd0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2fbe0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2fbf0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
2fc00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2fc10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2fc20 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
2fc30 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2fc40 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2fc50 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74  3_stmt.**.** Aft
2fc60 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
2fc70 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
2fc80 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
2fc90 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
2fca0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2fcb0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2fcc0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2fcd0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
2fce0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2fcf0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
2fd00 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
2fd10 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
2fd20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
2fd30 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2fd40 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2fd50 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
2fd60 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
2fd70 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
2fd80 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
2fd90 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
2fda0 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
2fdb0 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
2fdc0 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
2fdd0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
2fde0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
2fdf0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
2fe00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2fe10 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2fe20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2fe30 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
2fe40 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
2fe50 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
2fe60 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2fe70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2fe80 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
2fe90 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
2fea0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
2feb0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
2fec0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
2fed0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
2fee0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
2fef0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
2ff00 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
2ff10 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
2ff20 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
2ff30 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
2ff40 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
2ff50 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
2ff60 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
2ff70 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
2ff80 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
2ff90 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
2ffa0 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
2ffb0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
2ffc0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
2ffd0 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
2ffe0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
2fff0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
30000 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
30010 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
30020 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
30030 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
30040 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
30050 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
30060 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
30070 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
30080 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
30090 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
300a0 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
300b0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
300c0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
300d0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
300e0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
300f0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
30100 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
30110 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
30120 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
30130 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
30140 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
30150 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
30160 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
30170 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
30180 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
30190 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
301a0 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
301b0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
301c0 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
301d0 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
301e0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
301f0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
30200 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
30210 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
30220 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
30230 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
30240 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
30250 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
30260 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
30270 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
30280 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
30290 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
302a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
302b0 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
302c0 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
302d0 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
302e0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
302f0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
30300 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
30310 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
30320 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
30330 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
30340 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
30350 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
30360 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
30370 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
30380 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
30390 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
303a0 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
303b0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
303c0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
303d0 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
303e0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
303f0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
30400 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
30410 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
30420 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
30430 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
30440 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
30450 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
30460 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
30470 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
30480 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
30490 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
304a0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
304b0 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
304c0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
304d0 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
304e0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
304f0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
30500 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
30510 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
30520 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
30530 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
30540 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30550 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
30560 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30570 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
30580 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
30590 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
305a0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
305b0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
305c0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
305d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
305e0 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
305f0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
30600 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
30610 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
30620 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
30630 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
30640 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30650 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
30660 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
30670 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
30680 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
30690 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
306a0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
306b0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
306c0 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
306d0 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
306e0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
306f0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
30700 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
30710 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
30720 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
30730 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
30740 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
30750 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
30760 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
30770 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
30780 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
30790 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
307a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
307b0 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
307c0 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
307d0 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
307e0 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
307f0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
30800 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
30810 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
30820 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
30830 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
30840 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
30850 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
30860 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
30870 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30880 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
30890 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
308a0 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
308b0 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
308c0 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
308d0 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e  [version 3.6.23.
308e0 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  1] ([dateof:3.6.
308f0 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65  23.1],.** sqlite
30900 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
30910 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
30920 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
30930 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
30940 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
30950 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
30960 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
30970 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
30980 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
30990 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
309a0 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
309b0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
309c0 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
309d0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
309e0 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
309f0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
30a00 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
30a10 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
30a20 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
30a30 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
30a40 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
30a50 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
30a60 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
30a70 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
30a80 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
30a90 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
30aa0 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
30ab0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
30ac0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
30ad0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
30ae0 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
30af0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
30b00 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
30b10 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
30b20 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
30b30 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
30b40 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
30b50 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
30b60 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
30b70 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
30b80 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
30b90 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
30ba0 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
30bb0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
30bc0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
30bd0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
30be0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
30bf0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
30c00 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
30c10 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
30c20 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
30c30 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
30c40 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
30c50 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
30c60 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
30c70 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
30c80 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
30c90 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
30ca0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
30cb0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
30cc0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
30cd0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
30ce0 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
30cf0 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
30d00 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
30d10 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
30d20 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
30d30 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
30d40 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
30d50 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
30d60 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
30d70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30d80 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
30d90 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
30da0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
30db0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
30dc0 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
30dd0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30de0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30df0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
30e00 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30e10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
30e20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
30e30 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
30e40 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
30e50 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
30e60 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
30e70 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
30e80 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
30e90 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
30ea0 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
30eb0 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
30ec0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
30ed0 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
30ee0 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
30ef0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
30f00 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
30f10 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
30f20 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
30f30 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
30f40 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
30f50 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
30f60 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
30f70 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
30f80 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
30f90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
30fa0 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
30fb0 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
30fc0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
30fd0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
30fe0 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
30ff0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31000 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
31010 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
31020 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
31030 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
31040 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
31050 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
31060 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
31070 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
31080 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
31090 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
310a0 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
310b0 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
310c0 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
310d0 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
310e0 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
310f0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
31100 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
31110 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
31120 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
31130 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
31140 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
31150 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31160 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
31170 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
31180 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
31190 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
311a0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
311b0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
311c0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
311d0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
311e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
311f0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
31200 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
31210 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
31220 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
31230 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
31240 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
31250 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
31260 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
31270 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
31280 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
31290 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
312a0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
312b0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
312c0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
312d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
312e0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
312f0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
31300 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
31310 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
31320 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
31330 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
31340 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
31350 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
31360 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
31370 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
31380 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
31390 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
313a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
313b0 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
313c0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
313d0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
313e0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
313f0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
31400 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
31410 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
31420 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
31430 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
31440 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
31450 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
31460 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
31470 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
31480 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
31490 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
314a0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
314b0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
314c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
314d0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
314e0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
314f0 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
31500 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
31510 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
31520 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
31530 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
31540 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
31550 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
31560 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
31570 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
31580 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
31590 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
315a0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
315b0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
315c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
315d0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
315e0 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
315f0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
31600 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
31610 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
31620 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
31630 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
31640 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
31650 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
31660 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
31670 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
31680 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
31690 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
316a0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
316b0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
316c0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
316d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
316e0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
316f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
31700 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
31710 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
31720 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
31730 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
31740 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
31750 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
31760 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
31770 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31780 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
31790 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
317a0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
317b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
317c0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
317d0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
317e0 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
317f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
31800 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
31810 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
31820 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
31830 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
31840 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
31850 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
31860 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
31870 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
31880 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
31890 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
318a0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
318b0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
318c0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
318d0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
318e0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
318f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
31900 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31910 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
31920 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
31930 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
31940 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
31950 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
31960 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
31970 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
31980 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
31990 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
319a0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
319b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
319c0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
319d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
319e0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
319f0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
31a00 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
31a10 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
31a20 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
31a30 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
31a40 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
31a50 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
31a60 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
31a70 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
31a80 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
31a90 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
31aa0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
31ab0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
31ac0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
31ad0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
31ae0 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
31af0 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
31b00 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
31b10 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
31b20 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
31b30 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
31b40 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
31b50 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
31b60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31b70 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
31b80 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
31b90 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
31ba0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
31bb0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
31bc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
31bd0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
31be0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
31bf0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
31c00 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
31c10 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
31c20 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
31c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31c40 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
31c50 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
31c60 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
31c70 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
31c80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
31c90 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
31ca0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
31cb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31cc0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
31cd0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
31ce0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
31cf0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
31d00 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
31d10 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
31d20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
31d30 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
31d40 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
31d50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
31d60 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
31d70 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
31d80 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
31d90 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
31da0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
31db0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
31dc0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
31dd0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
31de0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
31df0 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
31e00 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
31e10 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31e20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
31e30 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
31e40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31e50 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
31e60 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
31e70 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
31e80 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
31e90 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
31ea0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
31eb0 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
31ec0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
31ed0 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
31ee0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
31ef0 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
31f00 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
31f10 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
31f20 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
31f30 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
31f40 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
31f50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31f60 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
31f70 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
31f80 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
31f90 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
31fa0 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
31fb0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
31fc0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
31fd0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
31fe0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
31ff0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
32000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32010 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
32020 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
32030 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
32040 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
32050 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
32060 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
32070 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
32080 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
32090 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
320a0 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
320b0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
320c0 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
320d0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
320e0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
320f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32100 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32110 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32120 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
32130 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
32140 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
32150 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
32160 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
32170 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
32180 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
32190 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
321a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
321b0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
321c0 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
321d0 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
321e0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
321f0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
32200 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
32210 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
32220 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
32230 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
32240 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
32250 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
32260 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
32270 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
32280 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
32290 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
322a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
322b0 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
322c0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
322d0 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
322e0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
322f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
32300 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
32310 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
32320 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
32330 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
32340 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
32350 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
32360 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
32370 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32380 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
32390 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
323a0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
323b0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
323c0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
323d0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
323e0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
323f0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
32400 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32410 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
32420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
32430 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
32440 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
32450 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  adsafe..**.** Th
32460 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
32470 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
32480 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
32490 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
324a0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
324b0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
324c0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
324d0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
324e0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
324f0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
32500 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
32510 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
32520 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
32530 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
32540 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
32550 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
32560 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
32570 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
32580 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
32590 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
325a0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
325b0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
325c0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
325d0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
325e0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
325f0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
32600 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
32610 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
32620 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
32630 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
32640 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
32650 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
32660 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
32670 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
32680 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
32690 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
326a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
326b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
326c0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
326d0 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
326e0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
326f0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
32700 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
32710 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
32720 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
32730 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
32740 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
32750 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
32760 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
32770 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
32780 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
32790 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
327a0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
327b0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
327c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
327d0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
327e0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
327f0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
32800 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
32810 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
32820 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
32830 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
32840 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
32850 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
32860 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
32870 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
32880 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
32890 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
328a0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
328b0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
328c0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
328d0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
328e0 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
328f0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
32900 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
32910 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
32920 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
32930 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
32940 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
32950 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
32960 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
32970 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
32980 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
32990 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
329a0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
329b0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
329c0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
329d0 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
329e0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
329f0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
32a00 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
32a10 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
32a20 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
32a30 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
32a40 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
32a50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
32a60 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
32a70 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
32a80 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
32a90 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
32aa0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
32ab0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
32ac0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
32ad0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
32ae0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
32af0 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
32b00 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
32b10 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
32b20 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
32b30 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
32b40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32b50 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
32b60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32b70 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
32b80 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
32b90 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
32ba0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
32bb0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
32bc0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
32bd0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
32be0 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
32bf0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
32c00 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
32c10 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
32c20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
32c30 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
32c40 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
32c50 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
32c60 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
32c70 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
32c80 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
32c90 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
32ca0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
32cb0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
32cc0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
32cd0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
32ce0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
32cf0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
32d00 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
32d10 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
32d20 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
32d30 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
32d40 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
32d50 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
32d60 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
32d70 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
32d80 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
32d90 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
32da0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
32db0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
32dc0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
32dd0 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
32de0 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
32df0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
32e00 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
32e10 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
32e20 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
32e30 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
32e40 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
32e50 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
32e60 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
32e70 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
32e80 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
32e90 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
32ea0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
32eb0 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
32ec0 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
32ed0 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
32ee0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
32ef0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
32f00 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
32f10 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
32f20 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
32f30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32f40 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
32f50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
32f60 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
32f70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32f80 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
32f90 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
32fa0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
32fb0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
32fc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32fd0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
32fe0 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
32ff0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
33000 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
33010 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
33020 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33030 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
33040 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33050 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
33060 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
33070 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
33080 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
33090 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
330a0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
330b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
330c0 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
330d0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
330e0 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
330f0 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
33100 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33110 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
33120 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
33130 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
33140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33150 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
33160 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
33170 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
33180 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
33190 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
331a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
331b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
331c0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
331d0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
331e0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
331f0 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
33200 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
33210 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
33220 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
33230 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
33240 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
33250 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
33260 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
33270 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
33280 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
33290 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
332a0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
332b0 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f  y.  Do <em>not</
332c0 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  em> pass the poi
332d0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
332e0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
332f0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
33300 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33310 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
33320 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
33330 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
33340 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
33350 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
33360 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
33370 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
33380 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
33390 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
333a0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
333b0 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
333c0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
333d0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
333e0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
333f0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
33400 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
33410 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
33420 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
33430 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
33440 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
33450 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
33460 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
33470 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
33480 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
33490 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
334a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
334b0 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
334c0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
334d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
334e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
334f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33500 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
33510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
33520 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
33530 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
33540 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
33550 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
33560 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
33570 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
33580 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
33590 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
335a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
335b0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
335c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
335d0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
335e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
335f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
33600 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
33610 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33620 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
33630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
33640 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
33650 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
33660 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
33670 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
33680 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33690 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
336a0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
336b0 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
336c0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
336d0 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
336e0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
336f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
33700 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
33710 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
33720 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
33730 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
33740 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
33750 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
33760 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
33770 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
33780 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
33790 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
337a0 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
337b0 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
337c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
337d0 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
337e0 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
337f0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
33800 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
33810 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
33820 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
33830 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
33840 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
33850 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
33860 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
33870 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
33880 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
33890 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
338a0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
338b0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
338c0 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
338d0 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
338e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
338f0 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
33900 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
33910 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
33920 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
33930 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
33940 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
33950 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
33960 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
33970 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
33980 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
33990 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
339a0 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
339b0 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
339c0 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
339d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
339e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
339f0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
33a00 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
33a10 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
33a20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
33a30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33a40 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
33a50 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
33a60 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
33a70 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
33a80 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
33a90 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
33aa0 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
33ab0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
33ac0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
33ad0 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
33ae0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
33af0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
33b00 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
33b10 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
33b20 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
33b30 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
33b40 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
33b50 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
33b60 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
33b70 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
33b80 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
33b90 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
33ba0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33bb0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
33bc0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
33bd0 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ect.** METHOD: s
33be0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
33bf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
33c00 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
33c10 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
33c20 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
33c30 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
33c40 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
33c50 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
33c60 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
33c70 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
33c80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
33c90 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
33ca0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
33cb0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
33cc0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
33cd0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
33ce0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
33cf0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
33d00 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
33d10 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
33d20 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
33d30 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
33d40 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
33d50 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
33d60 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
33d70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33d80 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
33d90 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
33da0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
33db0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
33dc0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
33dd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
33de0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
33df0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33e00 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
33e10 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
33e20 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
33e30 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
33e40 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
33e50 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
33e60 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
33e70 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
33e80 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
33e90 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
33ea0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
33eb0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
33ec0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
33ed0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
33ee0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
33ef0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
33f00 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
33f10 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
33f20 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
33f30 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
33f40 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
33f50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
33f60 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
33f70 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
33f80 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
33f90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
33fa0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
33fb0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
33fc0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
33fd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
33fe0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
33ff0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
34000 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
34010 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
34020 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
34030 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
34040 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
34050 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
34060 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
34070 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34080 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
34090 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
340a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
340b0 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
340c0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
340d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
340e0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
340f0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
34100 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
34110 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
34120 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
34130 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
34140 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
34150 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
34160 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
34170 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
34180 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
34190 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
341a0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
341b0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
341c0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
341d0 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
341e0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
341f0 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
34200 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
34210 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
34220 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
34230 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
34240 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
34250 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
34260 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
34270 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
34280 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
34290 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
342a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
342b0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
342c0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
342d0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
342e0 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
342f0 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
34300 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
34310 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
34320 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
34330 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
34340 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
34350 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
34360 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34370 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
34380 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
34390 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
343a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
343b0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
343c0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
343d0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
343e0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
343f0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
34400 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
34410 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
34420 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
34430 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
34440 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
34450 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
34460 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
34470 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
34480 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
34490 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
344a0 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
344b0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
344c0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
344d0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
344e0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
344f0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
34500 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
34510 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
34520 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
34530 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
34540 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
34550 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
34560 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
34570 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
34580 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
34590 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
345a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
345b0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
345c0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
345d0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
345e0 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
345f0 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
34600 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
34610 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
34620 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
34630 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
34640 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
34650 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
34660 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
34670 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
34680 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
34690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
346a0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
346b0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
346c0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
346d0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
346e0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
346f0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
34700 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
34710 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
34720 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
34730 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
34740 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
34750 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
34760 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
34770 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
34780 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
34790 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
347a0 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
347b0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
347c0 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
347d0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
347e0 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
347f0 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
34800 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
34810 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
34820 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
34830 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
34840 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
34850 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
34860 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
34870 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
34880 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
34890 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
348a0 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
348b0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
348c0 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
348d0 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
348e0 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
348f0 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
34900 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
34910 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
34920 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
34930 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
34940 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
34950 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
34960 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
34970 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
34980 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
34990 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
349a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
349b0 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
349c0 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
349d0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
349e0 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
349f0 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
34a00 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
34a10 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
34a20 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
34a30 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
34a40 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
34a50 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
34a60 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
34a70 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
34a80 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
34a90 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
34aa0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
34ab0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
34ac0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
34ad0 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
34ae0 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
34af0 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
34b00 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
34b10 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
34b20 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
34b30 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
34b40 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
34b50 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
34b60 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
34b70 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
34b80 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
34b90 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
34ba0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
34bb0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
34bc0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
34bd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34be0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
34bf0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
34c00 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
34c10 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
34c20 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
34c30 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
34c40 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
34c50 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
34c60 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
34c70 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
34c80 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
34c90 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
34ca0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
34cb0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
34cc0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
34cd0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
34ce0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
34cf0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
34d00 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
34d10 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
34d20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
34d30 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
34d40 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
34d50 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
34d60 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
34d70 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
34d80 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
34d90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34da0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
34db0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
34dc0 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
34dd0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
34de0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
34df0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
34e00 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
34e10 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
34e20 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
34e30 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
34e40 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
34e50 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
34e60 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
34e70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34e80 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
34e90 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
34ea0 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
34eb0 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
34ec0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
34ed0 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
34ee0 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
34ef0 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
34f00 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
34f10 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
34f20 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
34f30 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
34f40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34f50 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
34f60 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
34f70 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
34f80 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
34f90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34fa0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
34fb0 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
34fc0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
34fd0 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
34fe0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
34ff0 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
35000 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
35010 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
35020 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
35030 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
35040 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
35050 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
35060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
35070 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35080 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
35090 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
350a0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
350b0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
350c0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
350d0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
350e0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
350f0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
35100 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
35110 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
35120 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
35130 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
35140 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
35150 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
35160 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
35170 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
35180 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
35190 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
351a0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
351b0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
351c0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
351d0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
351e0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
351f0 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
35200 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
35210 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
35220 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35230 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
35240 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
35250 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
35260 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
35270 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
35280 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
35290 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
352a0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
352b0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
352c0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
352d0 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
352e0 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
352f0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
35300 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
35310 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
35320 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
35330 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
35340 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
35350 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
35360 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
35370 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
35380 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
35390 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
353a0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
353b0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
353c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
353d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
353e0 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
353f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35400 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
35410 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
35420 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
35430 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
35440 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
35450 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
35460 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
35470 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
35480 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
35490 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
354a0 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
354b0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
354c0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
354d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
354e0 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
354f0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
35500 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
35510 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
35520 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
35530 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
35540 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
35550 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35560 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
35570 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
35580 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
35590 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
355a0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
355b0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
355c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
355d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
355e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
355f0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
35600 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
35610 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
35620 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
35630 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
35640 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
35650 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
35660 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
35670 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
35680 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
35690 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
356a0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
356b0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
356c0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
356d0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
356e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
356f0 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
35700 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
35710 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
35720 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
35730 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
35740 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
35750 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
35760 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
35770 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
35780 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
35790 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
357a0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
357b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
357c0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
357d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
357e0 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
357f0 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
35800 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35810 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
35820 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
35830 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
35840 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
35850 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
35860 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
35870 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
35880 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
35890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
358a0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
358b0 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
358c0 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
358d0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
358e0 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
358f0 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
35900 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
35910 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
35920 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
35930 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
35940 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
35950 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
35960 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
35970 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
35980 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
35990 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
359a0 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
359b0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
359c0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
359d0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
359e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
359f0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
35a00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
35a10 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
35a20 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
35a30 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
35a40 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
35a50 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
35a60 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
35a70 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
35a80 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
35a90 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
35aa0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35ab0 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
35ac0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
35ad0 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
35ae0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35af0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
35b00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
35b10 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
35b20 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
35b30 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
35b40 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
35b50 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
35b60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
35b70 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
35b80 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
35b90 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
35ba0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
35bb0 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
35bc0 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
35bd0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
35be0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
35bf0 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
35c00 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
35c10 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
35c20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
35c30 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f  ctions.  To enco
35c40 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72  urage programmer
35c50 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68  s to avoid.** th
35c60 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
35c70 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61  e will not expla
35c80 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  in what they do.
35c90 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
35ca0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
35cb0 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
35cc0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
35cd0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
35ce0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35cf0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
35d00 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
35d10 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
35d20 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
35d30 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
35d40 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
35d50 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
35d60 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
35d70 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
35d80 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
35d90 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
35da0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
35db0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
35dc0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
35dd0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
35de0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
35df0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
35e00 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
35e10 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
35e20 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
35e30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35e40 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
35e50 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
35e60 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
35e70 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
35e80 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f   Values.** METHO
35e90 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  D: sqlite3_value
35ea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
35eb0 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
35ec0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
35ed0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
35ee0 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
35ef0 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
35f00 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
35f10 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
35f20 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
35f30 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
35f40 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a   aggregate.  .**
35f50 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
35f60 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
35f70 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
35f80 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
35f90 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
35fa0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35fb0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
35fc0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35fd0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
35fe0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
35ff0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
36000 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
36010 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
36020 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
36030 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
36040 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
36050 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
36060 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
36070 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
36080 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
36090 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
360a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
360b0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
360c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
360d0 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
360e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
360f0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
36100 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
36110 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
36120 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
36130 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
36140 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
36150 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36160 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36170 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
36180 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
36190 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
361a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
361b0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
361c0 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
361d0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
361e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
361f0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
36200 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
36210 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
36220 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
36230 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
36240 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  at these routine
36250 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
36260 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36270 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36280 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
36290 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
362a0 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
362b0 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
362c0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
362d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
362e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
362f0 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
36300 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
36310 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
36320 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
36330 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
36340 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
36350 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36360 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
36370 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
36380 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
36390 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
363a0 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
363b0 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
363c0 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
363d0 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
363e0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
363f0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
36400 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
36410 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
36420 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
36430 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
36440 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
36450 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
36460 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
36470 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
36480 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
36490 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
364a0 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
364b0 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
364c0 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
364d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
364e0 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
364f0 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
36500 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
36510 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
36520 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
36530 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
36540 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
36550 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
36560 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
36570 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
36580 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
36590 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
365a0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
365b0 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
365c0 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
365d0 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
365e0 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
365f0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
36600 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
36610 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
36620 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
36630 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
36640 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
36650 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
36660 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
36670 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
36680 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
36690 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
366a0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
366b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
366c0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
366d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
366e0 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
366f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
36700 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
36710 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
36720 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
36730 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
36740 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
36750 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
36760 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
36770 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
36780 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
36790 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
367a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
367b0 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
367c0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
367d0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
367e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
367f0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
36800 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
36810 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
36820 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
36830 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
36840 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
36850 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
36860 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
36870 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
36880 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
36890 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
368a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
368b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
368c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
368d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
368e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
368f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36900 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
36910 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
36920 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
36930 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
36940 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
36950 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
36960 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
36970 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
36980 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
36990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
369a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
369b0 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75  : Finding The Su
369c0 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c  btype Of SQL Val
369d0 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
369e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
369f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
36a00 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29 20  alue_subtype(V) 
36a10 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
36a20 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72   the subtype for
36a30 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74  .** an [applicat
36a40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
36a50 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65  function] argume
36a60 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 74 79  nt V.  The subty
36a70 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  pe.** informatio
36a80 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
36a90 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20   pass a limited 
36aa0 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78  amount of contex
36ab0 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51  t from.** one SQ
36ac0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e  L function to an
36ad0 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 65 20  other.  Use the 
36ae0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
36af0 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f  subtype()].** ro
36b00 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65  utine to set the
36b10 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 68 65   subtype for the
36b20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
36b30 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
36b40 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
36b50 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73  akes no use of s
36b60 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20  ubtype itself.  
36b70 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73  It merely passes
36b80 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20   the subtype.** 
36b90 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20  from the result 
36ba0 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74  of one [applicat
36bb0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
36bc0 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74  function] into t
36bd0 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61  he.** input of a
36be0 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67  nother..*/.unsig
36bf0 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  ned int sqlite3_
36c00 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71  value_subtype(sq
36c10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
36c20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36c30 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 51  Copy And Free SQ
36c40 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
36c50 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
36c60 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
36c70 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
36c80 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
36c90 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
36ca0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
36cb0 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20  ** object D and 
36cc0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
36cd0 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20  r to that copy. 
36ce0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76   ^The [sqlite3_v
36cf0 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a  alue] returned.*
36d00 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65  * is a [protecte
36d10 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36d20 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20   object even if 
36d30 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74  the input is not
36d40 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
36d50 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
36d60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36d70 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55   NULL if V is NU
36d80 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65  LL or if a.** me
36d90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
36da0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fails..**.** ^Th
36db0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
36dc0 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 63  free(V) interfac
36dd0 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69  e frees an [sqli
36de0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
36df0 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  t.** previously 
36e00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
36e10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
36e20 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61  ()].  ^If V is a
36e30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
36e40 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61   then sqlite3_va
36e50 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 61  lue_free(V) is a
36e60 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
36e70 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  .*/.sqlite3_valu
36e80 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e *sqlite3_value
36e90 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74  _dup(const sqlit
36ea0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
36eb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
36ec0 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ree(sqlite3_valu
36ed0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
36ee0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
36ef0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
36f00 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f  Context.** METHO
36f10 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
36f20 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
36f30 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
36f40 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
36f50 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
36f60 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
36f70 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
36f80 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
36f90 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
36fa0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
36fb0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
36fc0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
36fd0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
36fe0 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
36ff0 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
37000 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
37010 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
37020 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
37030 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
37040 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
37050 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
37060 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
37070 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
37080 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
37090 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
370a0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
370b0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
370c0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
370d0 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
370e0 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
370f0 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
37100 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37110 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
37120 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
37130 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
37140 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
37150 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
37160 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
37170 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
37180 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
37190 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
371a0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
371b0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
371c0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
371d0 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
371e0 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
371f0 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
37200 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
37210 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
37220 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
37230 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
37240 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
37250 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37260 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
37270 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
37280 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
37290 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
372a0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
372b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
372c0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
372d0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
372e0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
372f0 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
37300 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
37310 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
37320 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
37330 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
37340 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
37350 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
37360 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
37370 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
37380 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37390 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
373a0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
373b0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
373c0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
373d0 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
373e0 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
373f0 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
37400 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
37410 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37420 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
37430 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
37440 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
37450 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
37460 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
37470 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
37480 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
37490 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
374a0 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
374b0 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
374c0 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
374d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
374e0 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
374f0 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
37500 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
37510 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
37520 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
37530 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
37540 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
37550 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
37560 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37570 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
37580 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
37590 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
375a0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
375b0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
375c0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
375d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
375e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
375f0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
37600 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
37610 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
37620 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
37630 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
37640 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
37650 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
37660 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
37670 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
37680 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
37690 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
376a0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
376b0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
376c0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
376d0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
376e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
376f0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
37700 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
37710 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
37720 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
37730 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
37740 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
37750 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e  _context.**.** ^
37760 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
37770 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
37780 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
37790 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
377a0 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
377b0 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
377c0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
377d0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
377e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
377f0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
37800 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
37810 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
37820 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
37830 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
37840 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
37850 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
37860 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
37870 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
37880 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
37890 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
378a0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
378b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
378c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
378d0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
378e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
378f0 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
37900 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
37910 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
37920 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
37930 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  or Functions.** 
37940 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
37950 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54  context.**.** ^T
37960 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
37970 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
37980 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37990 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
379a0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
379b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
379c0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
379d0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
379e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
379f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
37a00 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
37a10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
37a20 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
37a30 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
37a40 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
37a50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
37a60 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
37a70 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
37a80 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
37a90 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
37aa0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
37ab0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
37ac0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
37ad0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37ae0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
37af0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
37b00 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
37b10 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29   (non-aggregate)
37b20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
37b30 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
37b40 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
37b50 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
37b60 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
37b70 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
37b80 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
37b90 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
37ba0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
37bb0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
37bc0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
37bd0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
37be0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
37bf0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
37c00 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20   preserved.  An 
37c10 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68  example.** of wh
37c20 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62  ere this might b
37c30 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61  e useful is in a
37c40 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
37c50 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20  ion matching.** 
37c60 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
37c70 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
37c80 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
37c90 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
37ca0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
37cb0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
37cc0 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72   with the patter
37cd0 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54  n string.  .** T
37ce0 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  hen as long as t
37cf0 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
37d00 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61  g remains the sa
37d10 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69  me,.** the compi
37d20 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
37d30 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
37d40 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
37d50 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
37d60 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
37d70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
37d80 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
37d90 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
37da0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
37db0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
37dc0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
37dd0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
37de0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
37df0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
37e00 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
37e10 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
37e20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37e30 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74   function. ^If t
37e40 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
37e50 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
37e60 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74  d with the funct
37e70 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68  ion argument, th
37e80 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  is sqlite3_get_a
37e90 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
37ea0 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ce.** returns a 
37eb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
37ec0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37ed0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
37ee0 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20  ,P,X) interface 
37ef0 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64  saves P as metad
37f00 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
37f10 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
37f20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37f30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37f40 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a  .  ^Subsequent.*
37f50 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
37f60 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
37f70 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f  ,N) return P fro
37f80 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  m the most recen
37f90 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  t.** sqlite3_set
37fa0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
37fb0 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65  ) call if the me
37fc0 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20  tadata is still 
37fd0 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c  valid or.** NULL
37fe0 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
37ff0 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72   has been discar
38000 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65  ded..** ^After e
38010 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
38020 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
38030 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58  C,N,P,X) where X
38040 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
38050 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
38060 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
38070 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  or function X wi
38080 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65  th parameter P e
38090 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20  xactly.** once, 
380a0 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74  when the metadat
380b0 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a  a is discarded..
380c0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
380d0 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65  e to discard the
380e0 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79   metadata at any
380f0 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67   time, including
38100 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5e  : <ul>.** <li> ^
38110 28 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73  (when the corres
38120 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
38130 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
38140 65 73 29 5e 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  es)^, or.** <li>
38150 20 5e 28 77 68 65 6e 20 5b 73 71 6c 69 74 65 33   ^(when [sqlite3
38160 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
38170 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
38180 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  ] is called for 
38190 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20  the.**      SQL 
381a0 73 74 61 74 65 6d 65 6e 74 29 5e 2c 20 6f 72 0a  statement)^, or.
381b0 2a 2a 20 3c 6c 69 3e 20 5e 28 77 68 65 6e 20 73  ** <li> ^(when s
381c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
381d0 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ta() is invoked 
381e0 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d  again on the sam
381f0 65 0a 2a 2a 20 20 20 20 20 20 20 70 61 72 61 6d  e.**       param
38200 65 74 65 72 29 5e 2c 20 6f 72 0a 2a 2a 20 3c 6c  eter)^, or.** <l
38210 69 3e 20 5e 28 64 75 72 69 6e 67 20 74 68 65 20  i> ^(during the 
38220 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33  original sqlite3
38230 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63  _set_auxdata() c
38240 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72  all when a memor
38250 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63  y .**      alloc
38260 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
38270 72 73 2e 29 5e 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  rs.)^ </ul>.**.*
38280 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20  * Note the last 
38290 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63  bullet in partic
382a0 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72  ular.  The destr
382b0 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73  uctor X in .** s
382c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
382d0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68  ta(C,N,P,X) migh
382e0 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65  t be called imme
382f0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20  diately, before 
38300 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  the.** sqlite3_s
38310 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
38320 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75  erface even retu
38330 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69  rns.  Hence sqli
38340 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
38350 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63  ).** should be c
38360 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65  alled near the e
38370 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nd of the functi
38380 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
38390 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e  n and the.** fun
383a0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
383b0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
383c0 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20  make any use of 
383d0 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74  P after.** sqlit
383e0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
383f0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
38400 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
38410 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
38420 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
38430 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
38440 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74  lls for.** funct
38450 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ion parameters t
38460 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d  hat are compile-
38470 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20  time constants, 
38480 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61  including litera
38490 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
384a0 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64  [parameters] and
384b0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d   expressions com
384c0 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73  posed from the s
384d0 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ame.)^.**.** The
384e0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
384f0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
38500 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
38510 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
38520 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
38530 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
38540 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
38550 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
38560 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
38570 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
38580 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
38590 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
385a0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
385b0 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
385c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
385d0 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
385e0 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
385f0 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
38600 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
38610 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
38620 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
38630 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
38640 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
38650 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
38660 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
38670 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
38680 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
38690 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
386a0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
386b0 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
386c0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
386d0 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
386e0 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
386f0 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
38700 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
38710 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
38720 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
38730 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
38740 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
38750 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
38760 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
38770 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
38780 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
38790 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
387a0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
387b0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
387c0 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
387d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
387e0 79 70 65 64 65 66 20 69 73 20 6e 65 63 6