SQLite Android Bindings
Hex Artifact Content
Not logged in

Artifact 880fe3b22a227f8396b9f300a4cae725c17b5773:


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 33 2e 31 36 2e  ON        "3.16.
1170: 30 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0".#define SQLIT
1180: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1190: 20 33 30 31 36 30 30 30 0a 23 64 65 66 69 6e 65   3016000.#define
11a0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
11b0: 44 20 20 20 20 20 20 22 32 30 31 37 2d 30 31 2d  D      "2017-01-
11c0: 30 32 20 31 31 3a 35 37 3a 35 38 20 30 34 61 63  02 11:57:58 04ac
11d0: 30 62 37 35 62 31 37 31 36 35 34 31 62 32 62 39  0b75b1716541b2b9
11e0: 37 37 30 34 66 34 38 30 39 63 62 37 65 66 31 39  7704f4809cb7ef19
11f0: 63 63 63 66 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  cccf"../*.** CAP
1200: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
1210: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
1220: 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f  Numbers.** KEYWO
1230: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72  RDS: sqlite3_ver
1240: 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75  sion sqlite3_sou
1250: 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  rceid.**.** Thes
1260: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f  e interfaces pro
1270: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
1280: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
1290: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
12a0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ],.** [SQLITE_VE
12b0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61  RSION_NUMBER], a
12c0: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  nd [SQLITE_SOURC
12d0: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
12e0: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62  ssor macros.** b
12f0: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65  ut are associate
1300: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
1310: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
1320: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
1330: 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72  ^(Cautious.** pr
1340: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
1350: 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29  include assert()
1360: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1370: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  heir application
1380: 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68   to.** verify th
1390: 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  at values return
13a0: 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65  ed by these inte
13b0: 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65  rfaces match the
13c0: 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68   macros in.** th
13d0: 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68  e header, and th
13e0: 75 73 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  us ensure that t
13f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1400: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
1410: 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72  th matching libr
1420: 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66  ary and header f
1430: 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  iles..**.** <blo
1440: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1450: 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33   assert( sqlite3
1460: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1470: 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52  er()==SQLITE_VER
1480: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a  SION_NUMBER );.*
1490: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
14a0: 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  (sqlite3_sourcei
14b0: 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43  d(),SQLITE_SOURC
14c0: 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61  E_ID)==0 );.** a
14d0: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71  ssert( strcmp(sq
14e0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
14f0: 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  (),SQLITE_VERSIO
1500: 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72  N)==0 );.** </pr
1510: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1520: 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1530: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
1540: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63  tring constant c
1550: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74  ontains the text
1560: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   of [SQLITE_VERS
1570: 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20  ION].** macro.  
1580: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62  ^The sqlite3_lib
1590: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
15a0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  on returns a poi
15b0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74  nter to the.** t
15c0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65  o the sqlite3_ve
15d0: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
15e0: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71  onstant.  The sq
15f0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1600: 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ().** function i
1610: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75  s provided for u
1620: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65  se in DLLs since
1630: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c   DLL users usual
1640: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a  ly do not have.*
1650: 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20  * direct access 
1660: 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  to string consta
1670: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44  nts within the D
1680: 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  LL.  ^The.** sql
1690: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
16a0: 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f  number() functio
16b0: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  n returns an int
16c0: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a  eger equal to.**
16d0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
16e0: 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20  _NUMBER].  ^The 
16f0: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1700: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1710: 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  rns .** a pointe
1720: 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f  r to a string co
1730: 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c  nstant whose val
1740: 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  ue is the same a
1750: 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  s the .** [SQLIT
1760: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
1770: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1780: 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  o..**.** See als
1790: 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69  o: [sqlite_versi
17a0: 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
17b0: 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a  e_source_id()]..
17c0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  */.SQLITE_API SQ
17d0: 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73  LITE_EXTERN cons
17e0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76  t char sqlite3_v
17f0: 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45  ersion[];.SQLITE
1800: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
1810: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  *sqlite3_libvers
1820: 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ion(void);.SQLIT
1830: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
1840: 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65   *sqlite3_source
1850: 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  id(void);.SQLITE
1860: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1870: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1880: 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  er(void);../*.**
1890: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
18a0: 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70  ime Library Comp
18b0: 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20  ilation Options 
18c0: 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a  Diagnostics.**.*
18d0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
18e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
18f0: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  d() function ret
1900: 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20  urns 0 or 1 .** 
1910: 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 68  indicating wheth
1920: 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65 64  er the specified
1930: 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69   option was defi
1940: 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69  ned at .** compi
1950: 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53  le time.  ^The S
1960: 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61  QLITE_ prefix ma
1970: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f  y be omitted fro
1980: 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e  m the .** option
1990: 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20   name passed to 
19a0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
19b0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a  ption_used().  .
19c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
19d0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
19e0: 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  _get() function 
19f0: 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67  allows iterating
1a00: 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73  .** over the lis
1a10: 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61  t of options tha
1a20: 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61  t were defined a
1a30: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62  t compile time b
1a40: 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74  y.** returning t
1a50: 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20  he N-th compile 
1a60: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69  time option stri
1a70: 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75  ng.  ^If N is ou
1a80: 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73  t of range,.** s
1a90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1aa0: 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72  tion_get() retur
1ab0: 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1ac0: 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  r.  ^The SQLITE_
1ad0: 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f   .** prefix is o
1ae0: 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20  mitted from any 
1af0: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1b00: 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
1b10: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b20: 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70  t()..**.** ^Supp
1b30: 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67  ort for the diag
1b40: 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nostic functions
1b50: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b60: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a  option_used().**
1b70: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d   and sqlite3_com
1b80: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1b90: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
1ba0: 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 68  by specifying th
1bb0: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d  e .** [SQLITE_OM
1bc0: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e  IT_COMPILEOPTION
1bd0: 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61  _DIAGS] option a
1be0: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a  t compile time..
1bf0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1c00: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73  SQL functions [s
1c10: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74  qlite_compileopt
1c20: 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ion_used()] and.
1c30: 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ** [sqlite_compi
1c40: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20  leoption_get()] 
1c50: 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65  and the [compile
1c60: 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d  _options pragma]
1c70: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
1c80: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1c90: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 4c  OPTION_DIAGS.SQL
1ca0: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1cb0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1cc0: 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61  n_used(const cha
1cd0: 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 51  r *zOptName);.SQ
1ce0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
1cf0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1d00: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1d10: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1d30: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1d40: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1d50: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1d60: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1d70: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1d80: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1d90: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1da0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1db0: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1dc0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1dd0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1de0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1df0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1e00: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1e10: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1e20: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1e30: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1e40: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1e50: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1e60: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1e70: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1e80: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1e90: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1ea0: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1eb0: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1ec0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1ed0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1ee0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1ef0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1f00: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1f10: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
1f20: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
1f30: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
1f40: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
1f50: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
1f60: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1f70: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1f80: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1f90: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1fa0: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1fb0: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1fc0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1fd0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1fe0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1ff0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
2000: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
2010: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2020: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2030: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2040: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2050: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2060: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2070: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2080: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2090: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
20a0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
20b0: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
20c0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
20d0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
20e0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
20f0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
2100: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
2110: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2120: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2130: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2140: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2150: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2160: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2170: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2180: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2190: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
21a0: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
21b0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
21c0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
21d0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
21e0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
21f0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
2200: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
2210: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2220: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2230: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2240: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2250: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2260: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2270: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2280: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2290: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
22a0: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
22b0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
22c0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
22d0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
22e0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
22f0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
2300: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
2310: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2320: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2330: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2340: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2350: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2360: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2370: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2380: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2390: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
23a0: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
23b0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
23c0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
23d0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
23e0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
23f0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
2400: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2410: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
2420: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2430: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
2440: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2450: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2460: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2470: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2480: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2490: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
24a0: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
24b0: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
24c0: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
24d0: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
24e0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
24f0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
2500: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
2510: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
2520: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
2530: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
2540: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2550: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2560: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2570: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2580: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2590: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25a0: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
25b0: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
25c0: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
25d0: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
25e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
25f0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
2600: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
2610: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2620: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
2630: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
2640: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2650: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2660: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
2670: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2680: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
2690: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
26a0: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
26b0: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
26c0: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
26d0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
26e0: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
26f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2700: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
2710: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
2720: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
2730: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
2740: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
2750: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
2760: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
2770: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
2780: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
2790: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
27a0: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
27b0: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
27c0: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
27d0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27e0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
27f0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
2800: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
2810: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
2820: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
2830: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
2840: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
2850: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
2860: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
2870: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
2880: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2890: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
28a0: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
28b0: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
28c0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
28d0: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
28e0: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
28f0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
2900: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
2910: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
2920: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
2930: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2940: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2950: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
2960: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
2970: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
2980: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
29a0: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
29b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
29c0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
29d0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
29e0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
29f0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
2a00: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
2a10: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
2a20: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
2a30: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
2a40: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2a50: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2a60: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2a70: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2a80: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2a90: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2aa0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
2ab0: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
2ac0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2ad0: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
2ae0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
2af0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
2b00: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
2b10: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
2b20: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
2b30: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
2b40: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2b50: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2b60: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2b70: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2b80: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2b90: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2ba0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2bb0: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
2bc0: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
2bd0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
2be0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2bf0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
2c00: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2c10: 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52  on.** DESTRUCTOR
2c20: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
2c30: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ^The sqlite3_clo
2c40: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  se() and sqlite3
2c50: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 74  _close_v2() rout
2c60: 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 63  ines are destruc
2c70: 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  tors.** for the 
2c80: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2c90: 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  ..** ^Calls to s
2ca0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2cb0: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2cc0: 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 51  _v2() return [SQ
2cd0: 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74  LITE_OK] if.** t
2ce0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2cf0: 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66 75  ect is successfu
2d00: 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e  lly destroyed an
2d10: 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64  d all associated
2d20: 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 72  .** resources ar
2d30: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a  e deallocated..*
2d40: 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  *.** ^If the dat
2d50: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d60: 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
2d70: 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20  ith unfinalized 
2d80: 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2d90: 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69  ements or unfini
2da0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2db0: 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  kup objects then
2dc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2dd0: 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 74  .** will leave t
2de0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2df0: 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20  ection open and 
2e00: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
2e10: 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  USY]..** ^If sql
2e20: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2e30: 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 75  is called with u
2e40: 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61  nfinalized prepa
2e50: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  red statements.*
2e60: 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73  * and/or unfinis
2e70: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  hed sqlite3_back
2e80: 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ups, then the da
2e90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ea0: 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20  n becomes.** an 
2eb0: 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65  unusable "zombie
2ec0: 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74  " which will aut
2ed0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65  omatically be de
2ee0: 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74  allocated when t
2ef0: 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61  he.** last prepa
2f00: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
2f10: 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68   finalized or th
2f20: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62  e last sqlite3_b
2f30: 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69  ackup is.** fini
2f40: 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  shed.  The sqlit
2f50: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e  e3_close_v2() in
2f60: 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
2f70: 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68  ded for use with
2f80: 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67  .** host languag
2f90: 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62  es that are garb
2fa0: 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61  age collected, a
2fb0: 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64  nd where the ord
2fc0: 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64  er in which.** d
2fd0: 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63  estructors are c
2fe0: 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61  alled is arbitra
2ff0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ry..**.** Applic
3000: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73  ations should [s
3010: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
3020: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
3030: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
3040: 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ents],.** [sqlit
3050: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20  e3_blob_close | 
3060: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42  close] all [BLOB
3070: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a   handles], and .
3080: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3090: 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69  up_finish | fini
30a0: 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33  sh] all [sqlite3
30b0: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
30c0: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
30d0: 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
30e0: 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74  ] object prior t
30f0: 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  o attempting to 
3100: 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74  close the object
3110: 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65  .  ^If.** sqlite
3120: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
3130: 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74  called on a [dat
3140: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3150: 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73  ] that still has
3160: 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  .** outstanding 
3170: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
3180: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
3190: 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  dles], and/or.**
31a0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
31b0: 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69  ] objects then i
31c0: 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  t returns [SQLIT
31d0: 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 65  E_OK] and the de
31e0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
31f0: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
3200: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
3210: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3220: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3230: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
3240: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
3250: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
3260: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
3270: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
3280: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
3290: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
32a0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
32b0: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
32c0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
32d0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
32e0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
32f0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3300: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
3310: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
3320: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
3330: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
3340: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
3350: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
3360: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
3370: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
3390: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
33a0: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
33b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
33c0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
33d0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
33e0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
33f0: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
3400: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
3410: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
3420: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
3430: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
3440: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
3450: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
3460: 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  e(sqlite3*);.SQL
3470: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
3480: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c  te3_close_v2(sql
3490: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  ite3*);../*.** T
34a0: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61  he type for a ca
34b0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e  llback function.
34c0: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61  .** This is lega
34d0: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65  cy and deprecate
34e0: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64  d.  It is includ
34f0: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
3500: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
3510: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f  ty and is not do
3520: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70  cumented..*/.typ
3530: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
3540: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69  e3_callback)(voi
3550: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63  d*,int,char**, c
3560: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  har**);../*.** C
3570: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65  API3REF: One-Ste
3580: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f  p Query Executio
3590: 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 4d  n Interface.** M
35a0: 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
35b0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
35c0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
35d0: 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e  e is a convenien
35e0: 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e  ce wrapper aroun
35f0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  d.** [sqlite3_pr
3600: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
3610: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
3620: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
3630: 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74  lize()],.** that
3640: 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69   allows an appli
3650: 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75  cation to run mu
3660: 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74  ltiple statement
3670: 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68  s of SQL.** with
3680: 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73  out having to us
3690: 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64  e a lot of C cod
36a0: 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e. .**.** ^The s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e  qlite3_exec() in
36c0: 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72  terface runs zer
36d0: 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20  o or more UTF-8 
36e0: 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69  encoded,.** semi
36f0: 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53  colon-separate S
3700: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
3710: 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e  ssed into its 2n
3720: 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69  d argument,.** i
3730: 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66  n the context of
3740: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
3750: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65  onnection] passe
3760: 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a  d in as its 1st.
3770: 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49  ** argument.  ^I
3780: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  f the callback f
3790: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33  unction of the 3
37a0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  rd argument to.*
37b0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
37c0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
37d0: 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  en it is invoked
37e0: 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74   for each result
37f0: 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f   row.** coming o
3800: 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61  ut of the evalua
3810: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
3820: 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  ts.  ^The 4th ar
3830: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
3840: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3850: 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 74  elayed through t
3860: 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d 65  o the 1st argume
3870: 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61  nt of each.** ca
3880: 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f  llback invocatio
3890: 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  n.  ^If the call
38a0: 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20  back pointer to 
38b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
38c0: 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  * is NULL, then 
38d0: 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65  no callback is e
38e0: 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20  ver invoked and 
38f0: 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a  result rows are.
3900: 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  ** ignored..**.*
3910: 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  * ^If an error o
3920: 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c  ccurs while eval
3930: 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73  uating the SQL s
3940: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3950: 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
3960: 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78  _exec(), then ex
3970: 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63  ecution of the c
3980: 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  urrent statement
3990: 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75   stops and.** su
39a0: 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65  bsequent stateme
39b0: 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e  nts are skipped.
39c0: 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61    ^If the 5th pa
39d0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
39e0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39f0: 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e  not NULL then an
3a00: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  y error message 
3a10: 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
3a20: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a  memory obtained.
3a30: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
3a40: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70  _malloc()] and p
3a50: 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75  assed back throu
3a60: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
3a70: 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69  eter..** To avoi
3a80: 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20  d memory leaks, 
3a90: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
3aa0: 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73  should invoke [s
3ab0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a  qlite3_free()].*
3ac0: 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  * on error messa
3ad0: 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  ge strings retur
3ae0: 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20  ned through the 
3af0: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  5th parameter of
3b00: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3b10: 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72  () after the err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3b30: 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e  g is no longer n
3b40: 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  eeded..** ^If th
3b50: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3b60: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3b70: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  ) is not NULL an
3b80: 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
3b90: 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  ccur, then sqlit
3ba0: 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74  e3_exec() sets t
3bb0: 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74  he pointer in it
3bc0: 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  s 5th parameter 
3bd0: 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72  to.** NULL befor
3be0: 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
3bf0: 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65  ** ^If an sqlite
3c00: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c10: 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
3c20: 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ro, the sqlite3_
3c30: 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  exec().** routin
3c40: 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  e returns SQLITE
3c50: 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69  _ABORT without i
3c60: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c  nvoking the call
3c70: 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a  back again and.*
3c80: 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e  * without runnin
3c90: 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  g any subsequent
3ca0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
3cb0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20  .**.** ^The 2nd 
3cc0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3cd0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3ce0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
3cf0: 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
3d00: 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
3d10: 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68  the result.  ^Th
3d20: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3d30: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3d40: 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  ec().** callback
3d50: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
3d60: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
3d70: 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20  ngs obtained as 
3d80: 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  if from.** [sqli
3d90: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
3da0: 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68  )], one for each
3db0: 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e   column.  ^If an
3dc0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a   element of a.**
3dd0: 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e   result row is N
3de0: 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72  ULL then the cor
3df0: 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e  responding strin
3e00: 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  g pointer for th
3e10: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
3e20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
3e30: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
3e40: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
3e50: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c  nt to the.** sql
3e60: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3e70: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3e80: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3e90: 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61  strings where ea
3ea0: 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72  ch.** entry repr
3eb0: 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20  esents the name 
3ec0: 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  of corresponding
3ed0: 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61   result column a
3ee0: 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
3ef0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
3f00: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
3f10: 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61  * ^If the 2nd pa
3f20: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3f30: 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e  e3_exec() is a N
3f40: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70  ULL pointer, a p
3f50: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20  ointer.** to an 
3f60: 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72  empty string, or
3f70: 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20   a pointer that 
3f80: 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68  contains only wh
3f90: 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20  itespace and/or 
3fa0: 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73  .** SQL comments
3fb0: 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74  , then no SQL st
3fc0: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
3fd0: 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64  luated and the d
3fe0: 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f  atabase.** is no
3ff0: 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  t changed..**.**
4000: 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a   Restrictions:.*
4010: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
4020: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
4030: 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68  n must ensure th
4040: 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d  at the 1st param
4050: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
4060: 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69  exec().**      i
4070: 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70  s a valid and op
4080: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
4090: 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69  nection]..** <li
40a0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
40b0: 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  n must not close
40c0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
40d0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
40e0: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  fied by.**      
40f0: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
4100: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
4110: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
4120: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
4130: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ing..** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  t not modify the
4160: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
4170: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  ext passed into.
4180: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20  **      the 2nd 
4190: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
41a0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
41b0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
41c0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
41d0: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ul>.*/.SQLITE_
41e0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
41f0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4200: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4220: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4230: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4240: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4250: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4260: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4270: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4280: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4290: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
42a0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
42b0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
42c0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
42d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42f0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4300: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4310: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4320: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4330: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4340: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4350: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4360: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4370: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4380: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4390: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
43a0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
43b0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
43c0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
43d0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
43e0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
43f0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4400: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4410: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4420: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4430: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4440: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4450: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4460: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4470: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4480: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4490: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
44a0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
44b0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
44c0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
44d0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
44e0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
44f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4500: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4510: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
4520: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
4530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4540: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4550: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4560: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4570: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4580: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4590: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
45a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
45b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
45c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
45d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
45e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
45f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4610: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4620: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4630: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4640: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4650: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4660: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4670: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4680: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4690: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
46a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
46b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
46c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
46e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
46f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4700: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4710: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4720: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4730: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4740: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4750: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4770: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4780: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4790: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
47a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
47b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
47c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
47d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
47e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
47f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4800: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4810: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4820: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4830: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4840: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4850: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4860: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4870: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4880: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4890: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
48a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
48b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
48c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
48d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
48e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
48f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4900: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4910: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4920: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4930: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4940: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4950: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4960: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4970: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4980: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4990: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
49a0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
49b0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
49c0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
49d0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
49e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
49f0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4a00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4a10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4a20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4a30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4a40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4a50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4a60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4a80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4a90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ab0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4ac0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4ad0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4ae0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4b00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4b10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4b20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4b30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4b40: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4b50: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4b60: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4b80: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4b90: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4ba0: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4bb0: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4bc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4bd0: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4be0: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4bf0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4c00: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4c10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4c20: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4c30: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4c40: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4c50: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4c60: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4c70: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4c80: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4c90: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4ca0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4cb0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4cc0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4cd0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4ce0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4cf0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4d00: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4d10: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4d20: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4d30: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4d40: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4d50: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4d60: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4d70: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4d80: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4d90: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4da0: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4db0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4dc0: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4dd0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4de0: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4df0: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4e00: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4e10: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4e20: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4e30: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4e40: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4e50: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4e60: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4e70: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4e80: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4e90: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4ea0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4eb0: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4ec0: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4ed0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4ee0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4ef0: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74  rsion 3.3.8 [dat
4f00: 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e  eof:3.3.8].** an
4f10: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4f20: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4f30: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4f40: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4f50: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4f60: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4f70: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4f80: 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20  These [extended 
4f90: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72  result codes] ar
4fa0: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4fb0: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4fc0: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4fd0: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4fe0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4ff0: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
5000: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20  t_codes()] API. 
5010: 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65   Or, the extende
5020: 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68  d code for.** th
5030: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72  e most recent er
5040: 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69  ror can be obtai
5050: 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
5060: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
5070: 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64  rrcode()]..*/.#d
5080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5090: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
50a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50b0: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
50c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
50d0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
50e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50f0: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
5100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5110: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
5120: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5130: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5140: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5150: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
5160: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5170: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5180: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5190: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
51a0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51b0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
51c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
51d0: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
51e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51f0: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
5200: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
5210: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
5220: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5230: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
5240: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
5250: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5260: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
5270: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5280: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
5290: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
52a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
52b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52c0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
52d0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52e0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
52f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5300: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
5310: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
5320: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
5330: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5340: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
5350: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5360: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
5370: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5380: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
5390: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
53a0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
53b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53c0: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
53d0: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
53e0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
53f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5400: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
5410: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5420: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
5430: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5440: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
5450: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5460: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
5470: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5480: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
5490: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
54a0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
54b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54c0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
54d0: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
54e0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
54f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5500: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
5510: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
5520: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
5530: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5540: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
5550: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
5560: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
5570: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5580: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
5590: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
55a0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
55b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55c0: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
55d0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
55e0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
55f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5600: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
5610: 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c  _NOENT      (SQL
5620: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c  ITE_IOERR | (23<
5630: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5640: 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20  ITE_IOERR_MMAP  
5650: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5660: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c  ITE_IOERR | (24<
5670: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5680: 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d  ITE_IOERR_GETTEM
5690: 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  PPATH       (SQL
56a0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c  ITE_IOERR | (25<
56b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56c0: 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41  ITE_IOERR_CONVPA
56d0: 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TH          (SQL
56e0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c  ITE_IOERR | (26<
56f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5700: 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20  ITE_IOERR_VNODE 
5710: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5720: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c  ITE_IOERR | (27<
5730: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5740: 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20  ITE_IOERR_AUTH  
5750: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5760: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c  ITE_IOERR | (28<
5770: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5780: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
5790: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
57a0: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
57b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
57c0: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
57d0: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
57e0: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
57f0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5800: 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53  QLITE_BUSY_SNAPS
5810: 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53  HOT           (S
5820: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
5830: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5840: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5850: 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28  NOTEMPDIR      (
5860: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5870: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5880: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5890: 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20  N_ISDIR         
58a0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
58b0: 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  N | (2<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
58d0: 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20  PEN_FULLPATH    
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
58f0: 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  PEN | (3<<8)).#d
5900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5910: 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20  TOPEN_CONVPATH  
5920: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5930: 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a  TOPEN | (4<<8)).
5940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5950: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5960: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5970: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5980: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5990: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
59a0: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
59b0: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
59c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
59d0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
59e0: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
59f0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
5a00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a10: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
5a20: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
5a30: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5a40: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5a50: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44  QLITE_READONLY_D
5a60: 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53  BMOVED        (S
5a70: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5a80: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a90: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5aa0: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5ab0: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5ac0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5ad0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ae0: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5af0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b00: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5b10: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5b20: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5b30: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b40: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b60: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5b70: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5b80: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ba0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5bb0: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5bc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5bd0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5be0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bf0: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5c00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c10: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5c20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c30: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5c40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c50: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c70: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5c80: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5c90: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5ca0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cb0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5cc0: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5cd0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5ce0: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5cf0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d00: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5d10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d20: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5d30: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5d40: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20  RAINT_ROWID     
5d50: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5d60: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a  RAINT |(10<<8)).
5d70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d80: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41  OTICE_RECOVER_WA
5d90: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e  L      (SQLITE_N
5da0: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a  OTICE | (1<<8)).
5db0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5dc0: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f  OTICE_RECOVER_RO
5dd0: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e  LLBACK (SQLITE_N
5de0: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a  OTICE | (2<<8)).
5df0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
5e00: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58  ARNING_AUTOINDEX
5e10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57         (SQLITE_W
5e20: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29  ARNING | (1<<8))
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20  AUTH_USER       
5e50: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e60: 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AUTH | (1<<8)).#
5e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
5e80: 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c  _LOAD_PERMANENTL
5e90: 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b  Y     (SQLITE_OK
5ea0: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5eb0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5ec0: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5ed0: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5ee0: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5ef0: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5f00: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5f10: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5f20: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5f30: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5f40: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5f50: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5f60: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5f70: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5f80: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5f90: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5fa0: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5fb0: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
5fc0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5fd0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5fe0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5ff0: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
6000: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
6010: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6020: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6030: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
6040: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6050: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
6060: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6070: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6080: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
6090: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
60a0: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
60b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60c0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
60d0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
60e0: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
60f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6100: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
6110: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
6120: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
6130: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6140: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
6150: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6160: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
6170: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6180: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6190: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
61a0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
61b0: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
61c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
61d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
61e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
61f0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
6200: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
6210: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6220: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
6230: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
6240: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
6250: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6260: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
6270: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
6280: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
6290: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62a0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
62b0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
62c0: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
62d0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62e0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
62f0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6300: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
6310: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6320: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
6330: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
6340: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
6350: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6360: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
6370: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
6380: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
6390: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
63a0: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
63b0: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
63c0: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
63d0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
63e0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
63f0: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
6400: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
6410: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
6420: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6430: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6440: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
6450: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
6460: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
6470: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6480: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6490: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
64a0: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
64b0: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
64c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
64d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
64e0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
64f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6500: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
6510: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
6520: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
6530: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6540: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
6550: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
6560: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
6570: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
6580: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6590: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
65a0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
65b0: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
65c0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
65d0: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
65e0: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
65f0: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
6600: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
6610: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
6620: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
6630: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
6640: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
6650: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
6660: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
6670: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
6680: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6690: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
66a0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
66b0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
66c0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
66d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
66e0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
66f0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
6700: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
6710: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6720: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6730: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
6740: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
6750: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
6760: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
6770: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
6780: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6790: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
67a0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
67b0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
67c0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
67d0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
67e0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
67f0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
6800: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
6810: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6820: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6830: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
6840: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6850: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
6860: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
6870: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
6880: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
6890: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
68a0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
68b0: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
68c0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
68d0: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
68e0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
68f0: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
6900: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
6910: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
6920: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
6930: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
6940: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
6950: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
6960: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
6970: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
6980: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
6990: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
69a0: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
69b0: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
69c0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
69d0: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
69e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
69f0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6a00: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
6a10: 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65  cate that a file
6a20: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
6a30: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
6a40: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
6a50: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
6a60: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
6a70: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
6a80: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
6a90: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
6aa0: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
6ab0: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
6ac0: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
6ad0: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  ileges..*/.#defi
6ae0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6af0: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6b00: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6b10: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6b20: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6b40: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6b50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6b60: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6b70: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6b90: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6ba0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6bb0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6bc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6bd0: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6be0: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c00: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6c10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6c20: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6c30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6c40: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6c50: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6c60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6c70: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6c80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6c90: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6ca0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6cb0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6cc0: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6cd0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6ce0: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6cf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d10: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6d30: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6d40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6d50: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6d60: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
6d70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6d80: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6d90: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
6da0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
6db0: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6dc0: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
6dd0: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a    0x00002000../*
6de0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6df0: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6e00: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6e10: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6e20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6e30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6e50: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6e60: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6e70: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6e80: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6e90: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6ea0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6eb0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6ec0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6ee0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6ef0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6f00: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6f10: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6f20: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6f30: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6f40: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6f50: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6f60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6f70: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6f80: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6f90: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6fa0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6fb0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
6fc0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6fd0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
6fe0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
6ff0: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
7000: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
7010: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
7020: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
7030: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7040: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
7050: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
7060: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
7070: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
7080: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
7090: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
70a0: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
70b0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
70c0: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
70d0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
70e0: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
70f0: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
7100: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
7110: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
7120: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7130: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
7140: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
7150: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
7160: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
7170: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
7180: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
7190: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
71a0: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
71b0: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
71c0: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
71d0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
71e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
71f0: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
7200: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
7210: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
7220: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
7230: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
7240: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
7250: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
7260: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
7270: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
7280: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
7290: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
72a0: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
72b0: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
72c0: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
72d0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
72e0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
72f0: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
7300: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
7310: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
7320: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
7330: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
7340: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
7350: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
7360: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
7370: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
7380: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
7390: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
73a0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
73b0: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
73c0: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
73d0: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
73e0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
73f0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7400: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
7410: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
7420: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
7430: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
7440: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
7450: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
7460: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
7470: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
7480: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7490: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
74a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
74b0: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
74c0: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
74d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
74e0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
74f0: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
7500: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7510: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
7520: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
7530: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7540: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
7550: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
7560: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
7570: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
7580: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
7590: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
75a0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
75b0: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
75c0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
75d0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
75e0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
75f0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
7600: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
7610: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
7620: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
7630: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7640: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7650: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
7660: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
7670: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
7680: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
7690: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
76a0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
76b0: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
76c0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
76d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
76e0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
76f0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7700: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
7710: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
7720: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
7730: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7740: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
7750: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
7760: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
7770: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
7780: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7790: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
77a0: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
77b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
77c0: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
77d0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
77e0: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
77f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7800: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
7810: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
7820: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
7830: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7840: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
7850: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
7860: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
7870: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
7880: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
7890: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
78a0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
78b0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
78c0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
78d0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
78e0: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
78f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7900: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
7910: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
7920: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
7930: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7940: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
7950: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
7960: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if 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 72 65 70 6f 72 74 65 64 20 74  Open] reported t
7990: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
79a0: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
79b0: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
79c0: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
79d0: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
79e0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
79f0: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
7a00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7a10: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7a20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7a30: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7a40: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7a50: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7a60: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7a70: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7a80: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7a90: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7aa0: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7ab0: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
7ac0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7ad0: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
7ae0: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
7af0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7b00: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
7b10: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7b20: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7b30: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7b40: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7b50: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7b60: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7b70: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7b80: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7b90: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7ba0: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7bb0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
7bc0: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7bd0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7be0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
7bf0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7c00: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
7c10: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7c20: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7c30: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7c40: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7c50: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7c60: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7c70: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7c80: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7c90: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7ca0: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7cb0: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7cc0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7cd0: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
7ce0: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7cf0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7d00: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7d10: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7d20: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7d30: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7d40: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7d50: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7d60: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7d70: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7d80: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7d90: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7da0: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7db0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7dc0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7dd0: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7de0: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7df0: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7e00: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7e10: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7e20: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7e30: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7e40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7e50: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7e60: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7e70: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7e80: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7e90: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7ea0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7eb0: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7ec0: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7ed0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7ee0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7ef0: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7f00: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7f10: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7f20: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7f30: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7f40: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7f50: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7f60: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7f70: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7f80: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7f90: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7fa0: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7fb0: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
7fc0: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7fd0: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
7fe0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
7ff0: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
8000: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
8010: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
8020: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
8030: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
8040: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
8050: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
8060: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e  ..** A [file con
8070: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c  trol opcodes | l
8080: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
8090: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
80a0: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
80b0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
80c0: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
80d0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
80e0: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
80f0: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
8100: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
8110: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
8120: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
8130: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
8140: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
8150: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
8160: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8170: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
8180: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
8190: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
81a0: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
81b0: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
81c0: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
81d0: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
81e0: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
81f0: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
8200: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
8210: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
8220: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
8230: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
8240: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
8250: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
8260: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
8270: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
8280: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8290: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
82a0: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
82b0: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
82c0: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
82d0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
82e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82f0: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
8300: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8310: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
8320: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8330: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
8340: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8350: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
8360: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8370: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
8380: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8390: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
83a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83b0: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
83c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
83d0: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
83e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
83f0: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8400: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8410: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
8420: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8430: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
8440: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
8450: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8460: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
8470: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
8480: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
8490: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
84a0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
84b0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
84c0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
84d0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
84e0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
84f0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
8500: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
8510: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8520: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
8530: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
8540: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
8550: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8560: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
8570: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
8580: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
8590: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
85a0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
85b0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
85c0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
85d0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
85e0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
85f0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
8600: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8610: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8620: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8630: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8640: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
8650: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
8660: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
8670: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
8680: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
8690: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
86a0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
86b0: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
86c0: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
86d0: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
86e0: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
86f0: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
8700: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8710: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8720: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8730: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8740: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
8750: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
8760: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
8770: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
8780: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
8790: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
87a0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
87b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
87c0: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
87d0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
87e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
87f0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8800: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8810: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8820: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8830: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8840: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8850: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8860: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8870: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
8880: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
8890: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
88a0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
88b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
88c0: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
88d0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
88e0: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
88f0: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
8900: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8910: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8920: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8930: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8940: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
8950: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
8960: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8970: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
8980: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8990: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
89a0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
89b0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
89c0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
89d0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
89e0: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
89f0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
8a00: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
8a10: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8a20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8a30: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
8a40: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
8a50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8a60: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8a70: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8a80: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
8a90: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
8aa0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8ab0: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
8ac0: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
8ad0: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
8ae0: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
8af0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
8b00: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
8b10: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8b20: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8b30: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8b40: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
8b50: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8b60: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
8b70: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8b80: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8b90: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
8ba0: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
8bb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8bc0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8bd0: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
8be0: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
8bf0: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
8c00: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8c10: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
8c20: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8c30: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8c40: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8c50: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
8c60: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
8c70: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
8c80: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
8c90: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
8ca0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
8cb0: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
8cc0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
8cd0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8ce0: 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f  pcodes} {file co
8cf0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a  ntrol opcode}.**
8d00: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8d10: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
8d20: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
8d30: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8d40: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
8d50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8d60: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
8d70: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
8d80: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
8d90: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
8da0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8db0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
8dc0: 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65  CKSTATE]].** The
8dd0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8de0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8df0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8e00: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8e10: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8e20: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8e30: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8e40: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8e50: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8e60: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
8e70: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
8e80: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
8e90: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
8ea0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
8eb0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8ec0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8ed0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8ee0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8ef0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8f00: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8f10: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8f20: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
8f30: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
8f40: 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  and is only avai
8f50: 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53  lable when the S
8f60: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f  QLITE_TEST.** co
8f70: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
8f80: 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
8f90: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8fa0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
8fb0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8fc0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
8fd0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
8fe0: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
8ff0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
9000: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
9010: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
9020: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
9030: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
9040: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
9050: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
9060: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
9070: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
9080: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
9090: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
90a0: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
90b0: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
90c0: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
90d0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
90e0: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
90f0: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
9100: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
9110: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
9120: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
9130: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
9140: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9150: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
9160: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9170: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
9180: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9190: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
91a0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
91b0: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
91c0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
91d0: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
91e0: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
91f0: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
9200: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
9210: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
9220: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
9230: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
9240: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
9250: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
9260: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
9270: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
9280: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
9290: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
92a0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
92b0: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
92c0: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
92d0: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
92e0: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
92f0: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
9300: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
9310: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
9320: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
9330: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
9340: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9350: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
9360: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9370: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
9380: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9390: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
93a0: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
93b0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
93c0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
93d0: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
93e0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
93f0: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f  ction.  See also
9400: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
9410: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e  OURNAL_POINTER].
9420: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9430: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9440: 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  L_POINTER]].** T
9450: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9460: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
9470: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9480: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
9490: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
94a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
94b0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
94c0: 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c  with the journal
94d0: 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a   file (either.**
94e0: 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a   the [rollback j
94f0: 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b  ournal] or the [
9500: 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d  write-ahead log]
9510: 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ) for a particul
9520: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9530: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9540: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
9550: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9560: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9570: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
9580: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9590: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
95a0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
95b0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
95c0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
95d0: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
95e0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
95f0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9600: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
9610: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
9620: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
9630: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
9640: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
9650: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
9660: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
9670: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9680: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9690: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
96a0: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
96b0: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
96c0: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
96d0: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
96e0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
96f0: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
9700: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
9710: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9720: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
9730: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
9740: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
9750: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
9760: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
9770: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
9780: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9790: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
97a0: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
97b0: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
97c0: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
97d0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
97e0: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
97f0: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
9800: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
9810: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
9820: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
9830: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
9840: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9850: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
9860: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9870: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9880: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
9890: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
98a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
98b0: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
98c0: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
98d0: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
98e0: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
98f0: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9900: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9910: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9920: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9930: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9940: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
9950: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9960: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
9970: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9980: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9990: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
99a0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
99b0: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
99c0: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
99d0: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
99e0: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
99f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
9a00: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
9a10: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
9a20: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
9a30: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9a40: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9a50: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
9a60: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9a70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9a80: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9a90: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9aa0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
9ab0: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
9ac0: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9ad0: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9ae0: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9af0: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9b00: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9b10: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
9b20: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9b30: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9b40: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
9b50: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
9b60: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
9b70: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
9b80: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
9b90: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9ba0: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9bb0: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9bc0: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9bd0: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9be0: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
9bf0: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
9c00: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
9c10: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
9c20: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
9c30: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
9c40: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
9c50: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
9c60: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
9c70: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
9c80: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
9c90: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9ca0: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9cb0: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9cc0: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9cd0: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9ce0: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
9cf0: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
9d00: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
9d10: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
9d20: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
9d30: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
9d40: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
9d50: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
9d60: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
9d70: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
9d80: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
9d90: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9da0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9db0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9dc0: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9dd0: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9de0: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
9df0: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
9e00: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
9e10: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
9e20: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
9e30: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
9e40: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
9e50: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
9e60: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
9e70: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
9e80: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
9e90: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9ea0: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9eb0: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9ec0: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9ed0: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
9ee0: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
9ef0: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
9f00: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
9f10: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
9f20: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
9f30: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
9f40: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
9f50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9f60: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
9f70: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9f80: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9f90: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9fa0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9fb0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9fc0: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
9fd0: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
9fe0: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
9ff0: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
a000: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
a010: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
a020: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
a030: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
a040: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
a050: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
a060: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
a070: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
a080: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
a090: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
a0a0: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
a0b0: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
a0c0: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
a0d0: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
a0e0: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
a0f0: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
a100: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
a110: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
a120: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
a130: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
a140: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
a150: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
a160: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
a170: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
a180: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a190: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
a1a0: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
a1b0: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
a1c0: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
a1d0: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
a1e0: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
a1f0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a200: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a210: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a220: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a230: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a240: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a250: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a260: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a270: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
a280: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
a290: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
a2a0: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
a2b0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
a2c0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
a2d0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
a2e0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
a2f0: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
a300: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
a310: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a320: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
a330: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
a340: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a350: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a360: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
a370: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
a380: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
a390: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
a3a0: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
a3b0: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
a3c0: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
a3d0: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
a3e0: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
a3f0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a400: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
a410: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
a420: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
a430: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
a440: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a450: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a460: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a470: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a480: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a490: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a4a0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a4b0: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
a4c0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
a4d0: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
a4e0: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
a4f0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
a500: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
a510: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
a520: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
a530: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
a540: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
a550: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a560: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
a570: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a580: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a590: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
a5a0: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
a5b0: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
a5c0: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
a5d0: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
a5e0: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
a5f0: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
a600: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
a610: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
a620: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
a630: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
a640: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
a650: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
a660: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
a670: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
a680: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a690: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a6a0: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
a6b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a6c0: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
a6d0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
a6e0: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
a6f0: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
a700: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
a710: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
a720: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
a730: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
a740: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
a750: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
a760: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a770: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
a780: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
a790: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
a7a0: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
a7b0: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
a7c0: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
a7d0: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
a7e0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a7f0: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
a800: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
a810: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
a820: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
a830: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
a840: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
a850: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
a860: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
a870: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
a880: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
a890: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
a8a0: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
a8b0: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
a8c0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a8d0: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
a8e0: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
a8f0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a900: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
a910: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
a920: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
a930: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
a940: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
a950: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a960: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
a970: 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NTER]].** ^The [
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 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
a9a0: 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72   finds a pointer
a9b0: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
a9c0: 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72  l.** [VFSes] cur
a9d0: 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20  rently in use.  
a9e0: 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58  ^(The argument X
a9f0: 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66   in.** sqlite3_f
aa00: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53  ile_control(db,S
aa10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
aa20: 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20  POINTER,X) must 
aa30: 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b  be.** of type "[
aa40: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22  sqlite3_vfs] **"
aa50: 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20  .  This opcodes 
aa60: 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74  will set *X.** t
aa70: 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  o a pointer to t
aa80: 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53  he top-level VFS
aa90: 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  .)^.** ^When the
aaa0: 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20  re are multiple 
aab0: 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65  VFS shims in the
aac0: 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63   stack, this opc
aad0: 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a  ode finds the.**
aae0: 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d   upper-most shim
aaf0: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
ab00: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ab10: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
ab20: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
ab30: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
ab40: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
ab50: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
ab60: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
ab70: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
ab80: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
ab90: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
aba0: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
abb0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
abc0: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
abd0: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
abe0: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
abf0: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
ac00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ac10: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
ac20: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
ac30: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
ac40: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
ac50: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
ac60: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
ac70: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
ac80: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
ac90: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
aca0: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
acb0: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
acc0: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
acd0: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
ace0: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
acf0: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
ad00: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
ad10: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ad20: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
ad30: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
ad40: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
ad50: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
ad60: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
ad70: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
ad80: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
ad90: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
ada0: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
adb0: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
adc0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
add0: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
ade0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
adf0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
ae00: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
ae10: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
ae20: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
ae30: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
ae40: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
ae50: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
ae60: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
ae70: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
ae80: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
ae90: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
aea0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
aeb0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aec0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
aed0: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
aee0: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
aef0: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
af00: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
af10: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
af20: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
af30: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
af40: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
af50: 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72  nt if result str
af60: 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20  ing is NULL, or 
af70: 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63  that returns a c
af80: 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  opy.** of the re
af90: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74  sult string if t
afa0: 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e  he string is non
afb0: 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68  -NULL..** ^If th
afc0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
afd0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
afe0: 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20  trol returns.** 
aff0: 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  any result code 
b000: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
b010: 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54  TE_OK] or [SQLIT
b020: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61  E_NOTFOUND], tha
b030: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  t means.** that 
b040: 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65  the VFS encounte
b050: 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69  red an error whi
b060: 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20  le handling the 
b070: 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65  [PRAGMA] and the
b080: 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  .** compilation 
b090: 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61  of the PRAGMA fa
b0a0: 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ils with an erro
b0b0: 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  r.  ^The [SQLITE
b0c0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
b0d0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  * file control o
b0e0: 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67  ccurs at the beg
b0f0: 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61  inning of pragma
b100: 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79   statement analy
b110: 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74  sis and so.** it
b120: 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72   is able to over
b130: 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50  ride built-in [P
b140: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
b150: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
b160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
b170: 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68  HANDLER]].** ^Th
b180: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b190: 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20  BUSYHANDLER].** 
b1a0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79  file-control may
b1b0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   be invoked by S
b1c0: 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74  QLite on the dat
b1d0: 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c  abase file handl
b1e0: 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74  e.** shortly aft
b1f0: 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20  er it is opened 
b200: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
b210: 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53  ide a custom VFS
b220: 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20   with access.** 
b230: 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  to the connectio
b240: 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  ns busy-handler 
b250: 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72  callback. The ar
b260: 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70  gument is of typ
b270: 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d  e (void **).** -
b280: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
b290: 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73   (void *) values
b2a0: 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69  . The first (voi
b2b0: 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f  d *) actually po
b2c0: 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e  ints.** to a fun
b2d0: 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69  ction of type (i
b2e0: 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e  nt (*)(void *)).
b2f0: 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76   In order to inv
b300: 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  oke the connecti
b310: 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64  ons.** busy-hand
b320: 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ler, this functi
b330: 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76  on should be inv
b340: 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65  oked with the se
b350: 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e  cond (void *) in
b360: 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73  .** the array as
b370: 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65   the only argume
b380: 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  nt. If it return
b390: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
b3a0: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
b3b0: 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72  * should be retr
b3c0: 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72  ied. If it retur
b3d0: 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73  ns zero, the cus
b3e0: 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61  tom VFS should a
b3f0: 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75  bandon the.** cu
b400: 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e  rrent operation.
b410: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b420: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
b430: 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70  LENAME]].** ^App
b440: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76  lication can inv
b450: 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  oke the [SQLITE_
b460: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
b470: 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  ME] file-control
b480: 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69  .** to have SQLi
b490: 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a  te generate a.**
b4a0: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
b4b0: 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ame using the sa
b4c0: 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61  me algorithm tha
b4d0: 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f  t is followed to
b4e0: 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d   generate.** tem
b4f0: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73  porary filenames
b500: 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73   for TEMP tables
b510: 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72   and other inter
b520: 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a  nal uses.  The.*
b530: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
b540: 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68  d be a char** wh
b550: 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c  ich will be fill
b560: 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65  ed with the file
b570: 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20  name.** written 
b580: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
b590: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
b5a0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
b5b0: 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64  he caller should
b5c0: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  .** invoke [sqli
b5d0: 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74  te3_free()] on t
b5e0: 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f  he result to avo
b5f0: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  id a memory leak
b600: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b610: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
b620: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
b630: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b640: 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
b650: 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71  rol is used to q
b660: 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a  uery or set the.
b670: 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ** maximum numbe
b680: 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20  r of bytes that 
b690: 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72  will be used for
b6a0: 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49   memory-mapped I
b6b0: 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  /O..** The argum
b6c0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
b6d0: 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74   to a value of t
b6e0: 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ype sqlite3_int6
b6f0: 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20  4 that.** is an 
b700: 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d  advisory maximum
b710: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b720: 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20   in the file to 
b730: 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65  memory map.  The
b740: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f  .** pointer is o
b750: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
b760: 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20  the old value.  
b770: 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  The limit is not
b780: 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74   changed if.** t
b790: 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61  he value origina
b7a0: 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69  lly pointed to i
b7b0: 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20  s negative, and 
b7c0: 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c  so the current l
b7d0: 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20  imit .** can be 
b7e0: 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69  queried by passi
b7f0: 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20  ng in a pointer 
b800: 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  to a negative nu
b810: 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66  mber.  This.** f
b820: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile-control is u
b830: 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
b840: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41  o implement [PRA
b850: 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a  GMA mmap_size]..
b860: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b870: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d  TE_FCNTL_TRACE]]
b880: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b890: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c  FCNTL_TRACE] fil
b8a0: 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64  e control provid
b8b0: 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f  es advisory info
b8c0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68  rmation.** to th
b8d0: 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74  e VFS about what
b8e0: 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65   the higher laye
b8f0: 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  rs of the SQLite
b900: 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67   stack are doing
b910: 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63  ..** This file c
b920: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62  ontrol is used b
b930: 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76  y some VFS activ
b940: 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69  ity tracing [shi
b950: 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ms]..** The argu
b960: 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74  ment is a zero-t
b970: 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
b980: 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73  .  Higher layers
b990: 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74   in the.** SQLit
b9a0: 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65  e stack may gene
b9b0: 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f  rate instances o
b9c0: 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  f this file cont
b9d0: 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53  rol if.** the [S
b9e0: 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f  QLITE_USE_FCNTL_
b9f0: 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  TRACE] compile-t
ba00: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
ba10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  abled..**.** <li
ba20: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ba30: 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54  HAS_MOVED]].** T
ba40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ba50: 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65  _HAS_MOVED] file
ba60: 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72   control interpr
ba70: 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74  ets its argument
ba80: 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   as a.** pointer
ba90: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61   to an integer a
baa0: 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62  nd it writes a b
bab0: 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74  oolean into that
bac0: 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69   integer dependi
bad0: 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  ng.** on whether
bae0: 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65   or not the file
baf0: 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65   has been rename
bb00: 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c  d, moved, or del
bb10: 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a  eted since it.**
bb20: 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65   was first opene
bb30: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
bb40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
bb50: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a  2_GET_HANDLE]].*
bb60: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bb70: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
bb80: 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NDLE] opcode can
bb90: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
bba0: 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  in the.** underl
bbb0: 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65  ying native file
bbc0: 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74   handle associat
bbd0: 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20 68  ed with a file h
bbe0: 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c  andle.  This fil
bbf0: 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  e.** control int
bc00: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
bc10: 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65  ment as a pointe
bc20: 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69  r to a native fi
bc30: 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a  le handle and.**
bc40: 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75   writes the resu
bc50: 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72  lting value ther
bc60: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
bc70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
bc80: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a  2_SET_HANDLE]].*
bc90: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bca0: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
bcb0: 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  NDLE] opcode is 
bcc0: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
bcd0: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
bce0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
bcf0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
bd00: 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66  od to swap the f
bd10: 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20  ile handle with 
bd20: 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74  the one.** point
bd30: 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72  ed to by the pAr
bd40: 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69  g argument.  Thi
bd50: 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20  s capability is 
bd60: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
bd70: 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20  ing.** and only 
bd80: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
bd90: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
bda0: 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65  E_TEST is define
bdb0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
bdc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
bdd0: 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b  BLOCK]].** The [
bde0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
bdf0: 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67  _BLOCK] is a sig
be00: 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c  nal to the VFS l
be10: 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67  ayer that it mig
be20: 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61  ht.** be advanta
be30: 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f  geous to block o
be40: 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c  n the next WAL l
be50: 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20  ock if the lock 
be60: 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65  is not immediate
be70: 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e  ly.** available.
be80: 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73    The WAL subsys
be90: 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20  tem issues this 
bea0: 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61  signal during ra
beb0: 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e  re.** circumstan
bec0: 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ces in order to 
bed0: 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69  fix a problem wi
bee0: 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65  th priority inve
bef0: 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63  rsion..** Applic
bf00: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65  ations should <e
bf10: 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74  m>not</em> use t
bf20: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
bf30: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
bf40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
bf50: 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  S]].** The [SQLI
bf60: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
bf70: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
bf80: 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73  mented by zipvfs
bf90: 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72   only. All other
bfa0: 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72  .** VFS should r
bfb0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54  eturn SQLITE_NOT
bfc0: 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f  FOUND for this o
bfd0: 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pcode..**.** <li
bfe0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bff0: 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  RBU]].** The [SQ
c000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20  LITE_FCNTL_RBU] 
c010: 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d  opcode is implem
c020: 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70 65  ented by the spe
c030: 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62 79  cial VFS used by
c040: 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74 65  .** the RBU exte
c050: 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c  nsion only.  All
c060: 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c   other VFS shoul
c070: 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  d return SQLITE_
c080: 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20  NOTFOUND for.** 
c090: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a  this opcode.  .*
c0a0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
c0b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c0c0: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
c0d0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
c0e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47  e SQLITE_FCNTL_G
c0f0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c100: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
c110: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
c120: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c130: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
c140: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
c150: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
c160: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
c170: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
c180: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
c190: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
c1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
c1b0: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
c1c0: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
c1d0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
c1e0: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
c1f0: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
c200: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
c210: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
c220: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
c230: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
c240: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
c250: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
c260: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
c270: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
c280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c290: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
c2a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
c2b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c2c0: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
c2d0: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
c2e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c2f0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
c300: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
c310: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c320: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
c330: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
c340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c350: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
c360: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
c370: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c380: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
c390: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
c3a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c3b0: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
c3c0: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
c3d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
c3e0: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
c3f0: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
c400: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
c410: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
c420: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
c430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
c440: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
c450: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
c460: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c470: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
c480: 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51     22.#define SQ
c490: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c4a0: 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _SET_HANDLE     
c4b0: 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    23.#define SQL
c4c0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
c4d0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
c4e0: 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   24.#define SQLI
c4f0: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20  TE_FCNTL_ZIPVFS 
c500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c510: 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  25.#define SQLIT
c520: 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20  E_FCNTL_RBU     
c530: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
c540: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
c550: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
c560: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37  ER            27
c570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c580: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
c590: 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a  INTER        28.
c5a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c5b0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c5c0: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23  ANDLE       29.#
c5d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c5e0: 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20  NTL_PDB         
c5f0: 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 0a 2f             30../
c600: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d  * deprecated nam
c610: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
c620: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
c630: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c640: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
c650: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c660: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
c670: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c680: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
c690: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
c6a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
c6b0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
c6c0: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c6d0: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a  TL_LAST_ERRNO...
c6e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c6f0: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
c700: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
c710: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
c720: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
c730: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
c740: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
c750: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
c760: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
c770: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
c780: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
c790: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
c7a0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
c7b0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
c7c0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
c7d0: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
c7e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
c7f0: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
c800: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
c810: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
c820: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
c830: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
c840: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c850: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
c860: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
c870: 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45  3REF: Loadable E
c880: 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a  xtension Thunk.*
c890: 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
c8a0: 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c  o the opaque sql
c8b0: 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65  ite3_api_routine
c8c0: 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 70  s structure is p
c8d0: 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20  assed as.** the 
c8e0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
c8f0: 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20  to entry points 
c900: 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74  of [loadable ext
c910: 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a  ensions].  This.
c920: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  ** structure mus
c930: 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20 69  t be typedefed i
c940: 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20  n order to work 
c950: 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20  around compiler 
c960: 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73  warnings.** on s
c970: 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  ome platforms..*
c980: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
c990: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
c9a0: 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70  tines sqlite3_ap
c9b0: 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a  i_routines;../*.
c9c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
c9d0: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
c9e0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
c9f0: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
ca00: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
ca10: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
ca20: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
ca30: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
ca40: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
ca50: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
ca60: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
ca70: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
ca80: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
ca90: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
caa0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
cab0: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
cac0: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
cad0: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
cae0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
caf0: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
cb00: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
cb10: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
cb20: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
cb30: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
cb40: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
cb50: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
cb60: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
cb70: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
cb80: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
cb90: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
cba0: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
cbb0: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
cbc0: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
cbd0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
cbe0: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
cbf0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
cc00: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
cc10: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
cc20: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
cc30: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
cc40: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
cc50: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
cc60: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
cc70: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
cc80: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
cc90: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
cca0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
ccb0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
ccc0: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
ccd0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
cce0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
ccf0: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
cd00: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
cd10: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
cd20: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
cd30: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
cd40: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
cd50: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
cd60: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
cd70: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
cd80: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
cd90: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
cda0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
cdb0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
cdc0: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
cdd0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
cde0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
cdf0: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
ce00: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
ce10: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
ce20: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
ce30: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
ce40: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
ce50: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
ce60: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
ce70: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
ce80: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
ce90: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
cea0: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
ceb0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
cec0: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
ced0: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
cee0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
cef0: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
cf00: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
cf10: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
cf20: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
cf30: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
cf40: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
cf50: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
cf60: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
cf70: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
cf80: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
cf90: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
cfa0: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
cfb0: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
cfc0: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
cfd0: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
cfe0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
cff0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
d000: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
d010: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
d020: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
d030: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
d040: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
d050: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
d060: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
d070: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
d080: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
d090: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
d0a0: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
d0b0: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
d0c0: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
d0d0: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
d0e0: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
d0f0: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
d100: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
d110: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
d120: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
d130: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
d140: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
d150: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
d160: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
d170: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
d180: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
d190: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
d1a0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
d1b0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
d1c0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
d1d0: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
d1e0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
d1f0: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
d200: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
d210: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
d220: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
d230: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
d240: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
d250: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
d260: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
d270: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
d280: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
d290: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
d2a0: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
d2b0: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
d2c0: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
d2d0: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
d2e0: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
d2f0: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
d300: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d310: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
d320: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
d330: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
d340: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
d350: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
d360: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d370: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
d380: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d390: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
d3a0: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
d3b0: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
d3c0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
d3d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
d3e0: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
d3f0: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
d400: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
d410: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
d420: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
d430: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
d440: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
d450: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
d460: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
d470: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
d480: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
d490: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
d4a0: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
d4b0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
d4c0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
d4d0: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
d4e0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
d4f0: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
d500: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
d510: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
d520: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
d530: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
d540: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
d550: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
d560: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
d570: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
d580: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d590: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
d5a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
d5b0: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
d5c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d5d0: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
d5e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d5f0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
d600: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d610: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
d620: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d630: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
d640: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d650: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
d660: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
d670: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d680: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
d690: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
d6a0: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
d6b0: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
d6c0: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
d6d0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
d6e0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
d6f0: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
d700: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
d710: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
d720: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
d730: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
d740: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
d750: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
d760: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
d770: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
d780: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
d790: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
d7a0: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
d7b0: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
d7c0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
d7d0: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
d7e0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
d7f0: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
d800: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
d810: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
d820: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
d830: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
d840: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
d850: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
d860: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
d870: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
d880: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
d890: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
d8a0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
d8b0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
d8c0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
d8d0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
d8e0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
d8f0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
d900: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
d910: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
d920: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
d930: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
d940: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
d950: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d960: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
d970: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
d980: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
d990: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
d9a0: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
d9b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
d9c0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
d9d0: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
d9e0: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
d9f0: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
da00: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
da10: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
da20: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
da30: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
da40: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
da50: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
da60: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
da70: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
da80: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
da90: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
daa0: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
dab0: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
dac0: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
dad0: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
dae0: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
daf0: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
db00: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
db10: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
db20: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
db30: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
db40: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
db50: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
db60: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
db70: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
db80: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
db90: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
dba0: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
dbb0: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
dbc0: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
dbd0: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
dbe0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
dbf0: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
dc00: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
dc10: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
dc20: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
dc30: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
dc40: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
dc50: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
dc60: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
dc70: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
dc80: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
dc90: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
dca0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
dcb0: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
dcc0: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
dcd0: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
dce0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
dcf0: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
dd00: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
dd10: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
dd20: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
dd30: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
dd40: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
dd50: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
dd60: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
dd70: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
dd80: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
dd90: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
dda0: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
ddb0: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
ddc0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
ddd0: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
dde0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
ddf0: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
de00: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
de10: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
de20: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
de30: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
de40: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
de50: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
de60: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
de70: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
de80: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
de90: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
dea0: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
deb0: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
dec0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
ded0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
dee0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
def0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
df00: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
df10: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
df20: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
df30: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
df40: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
df50: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
df60: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
df70: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
df80: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
df90: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
dfa0: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
dfb0: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
dfc0: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
dfd0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
dfe0: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
dff0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
e000: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
e010: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
e020: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
e030: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
e040: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
e050: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
e060: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
e070: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
e080: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
e090: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
e0a0: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
e0b0: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
e0c0: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
e0d0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
e0e0: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
e0f0: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
e100: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
e110: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
e120: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
e130: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
e140: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
e150: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
e160: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
e170: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
e180: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
e190: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
e1a0: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
e1b0: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
e1c0: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
e1d0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
e1e0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
e1f0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
e200: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
e210: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
e220: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
e230: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
e240: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
e250: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
e260: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
e270: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
e280: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
e290: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
e2a0: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
e2b0: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
e2c0: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
e2d0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
e2e0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
e2f0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
e300: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
e310: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
e320: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
e330: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
e340: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
e350: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
e360: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
e370: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
e380: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
e390: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e3a0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
e3b0: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
e3c0: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
e3d0: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
e3e0: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
e3f0: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
e400: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
e410: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
e420: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
e430: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
e440: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e450: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
e460: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
e470: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
e480: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
e490: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
e4a0: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
e4b0: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
e4c0: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
e4d0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
e4e0: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
e4f0: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
e500: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
e510: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
e520: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
e530: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
e540: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
e550: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
e560: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
e570: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
e580: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
e590: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
e5a0: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
e5b0: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
e5c0: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
e5d0: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
e5e0: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
e5f0: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
e600: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
e610: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
e620: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
e630: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
e640: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
e650: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
e660: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
e670: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
e680: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
e690: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
e6a0: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
e6b0: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
e6c0: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
e6d0: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
e6e0: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
e6f0: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
e700: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
e710: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
e720: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
e730: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
e740: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
e750: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
e760: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e770: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
e780: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
e790: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
e7a0: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
e7b0: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
e7c0: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
e7d0: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
e7e0: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
e7f0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
e800: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
e810: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
e820: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
e830: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
e840: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
e850: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
e860: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e870: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
e880: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
e890: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
e8a0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
e8b0: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
e8c0: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
e8d0: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
e8e0: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
e8f0: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
e900: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
e910: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
e920: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
e930: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
e940: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
e950: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
e960: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
e970: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
e980: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
e990: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
e9a0: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
e9b0: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
e9c0: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
e9d0: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
e9e0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
e9f0: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
ea00: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
ea10: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
ea20: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
ea30: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
ea40: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
ea50: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
ea60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
ea70: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
ea80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
ea90: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
eaa0: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
eab0: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
eac0: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
ead0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
eae0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
eaf0: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
eb00: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
eb10: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
eb20: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
eb30: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
eb40: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
eb50: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
eb60: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eb70: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
eb80: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
eb90: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
eba0: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
ebb0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ebc0: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
ebd0: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
ebe0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
ebf0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
ec00: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
ec10: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
ec20: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
ec30: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
ec40: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
ec50: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
ec60: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
ec70: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
ec80: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
ec90: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
eca0: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
ecb0: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
ecc0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ecd0: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
ece0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
ecf0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
ed00: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
ed10: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
ed20: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
ed30: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
ed40: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
ed50: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
ed60: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
ed70: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
ed80: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
ed90: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
eda0: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
edb0: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
edc0: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
edd0: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
ede0: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
edf0: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
ee00: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
ee10: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
ee20: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
ee30: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
ee40: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
ee50: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
ee60: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
ee70: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
ee80: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
ee90: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
eea0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
eeb0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
eec0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
eed0: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
eee0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
eef0: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
ef00: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
ef10: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ef20: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
ef30: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
ef40: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ef50: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ef60: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
ef70: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
ef80: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
ef90: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
efa0: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
efb0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
efc0: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
efd0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
efe0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  future versions.
eff0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
f000: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
f010: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
f020: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
f030: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
f040: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
f050: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
f060: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
f070: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
f080: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
f090: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
f0a0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
f0b0: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
f0c0: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
f0d0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
f0e0: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
f0f0: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
f100: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
f110: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
f120: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
f130: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
f140: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
f150: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f160: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
f170: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
f180: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
f190: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
f1a0: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
f1b0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
f1c0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
f1d0: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
f1e0: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
f1f0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
f200: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
f210: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
f220: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
f230: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
f240: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
f250: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
f260: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
f270: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
f280: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
f290: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
f2a0: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
f2b0: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
f2c0: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
f2d0: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
f2e0: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
f2f0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
f300: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
f310: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
f320: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
f330: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
f340: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
f350: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
f360: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
f370: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
f380: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
f390: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
f3a0: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
f3b0: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
f3c0: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
f3d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f3e0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
f3f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f400: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
f410: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
f420: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
f430: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
f440: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f450: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
f460: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
f470: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
f480: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
f490: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
f4a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
f4b0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
f4c0: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
f4d0: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
f4e0: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
f4f0: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
f500: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
f510: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
f520: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
f530: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
f540: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
f550: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
f560: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
f570: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f580: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f590: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
f5a0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f5b0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f5c0: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
f5d0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
f5e0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f5f0: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f600: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
f610: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
f620: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
f630: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f640: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
f650: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
f660: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
f670: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
f680: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
f690: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
f6a0: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
f6b0: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
f6c0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f6d0: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
f6e0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
f6f0: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
f700: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
f710: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
f720: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
f730: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
f740: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
f750: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
f760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f770: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
f780: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
f790: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
f7a0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
f7b0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f7c0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
f7d0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
f7e0: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
f7f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
f800: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
f810: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
f820: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
f830: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f840: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
f850: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
f860: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
f870: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
f880: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
f890: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
f8a0: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
f8b0: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
f8c0: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
f8d0: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
f8e0: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
f8f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f900: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
f910: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
f920: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
f930: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
f940: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f950: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f960: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
f970: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
f980: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
f990: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
f9a0: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
f9b0: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
f9c0: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
f9d0: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
f9e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f9f0: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
fa00: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
fa10: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
fa20: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
fa30: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
fa40: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
fa50: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
fa60: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
fa70: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
fa80: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
fa90: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
faa0: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
fab0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
fac0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
fad0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fae0: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
faf0: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
fb00: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
fb10: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
fb20: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
fb30: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
fb40: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
fb50: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
fb60: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
fb70: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
fb80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
fb90: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
fba0: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
fbb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fbc0: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
fbd0: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
fbe0: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
fbf0: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
fc00: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
fc10: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
fc20: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
fc30: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
fc40: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
fc50: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
fc60: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
fc70: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
fc80: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
fc90: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
fca0: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
fcb0: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
fcc0: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
fcd0: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
fce0: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
fcf0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
fd00: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
fd10: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
fd20: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
fd30: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
fd40: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
fd50: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
fd60: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fd70: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fd80: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
fd90: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
fda0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
fdb0: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
fdc0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fdd0: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
fde0: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
fdf0: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
fe00: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
fe10: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
fe20: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
fe30: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
fe40: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
fe50: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
fe60: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
fe70: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
fe80: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
fe90: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
fea0: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
feb0: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
fec0: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
fed0: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
fee0: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
fef0: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
ff00: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
ff10: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
ff20: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
ff30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
ff40: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
ff50: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
ff60: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
ff70: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
ff80: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
ff90: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ffa0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
ffb0: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
ffc0: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
ffd0: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
ffe0: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
fff0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
10000 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
10010 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
10020 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
10030 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
10040 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
10050 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10060 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
10070 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
10080 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
10090 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
100a0 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
100b0 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
100c0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
100d0 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
100e0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
100f0 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
10100 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
10110 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
10120 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
10130 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
10140 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
10150 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
10160 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
10170 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
10180 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
10190 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
101a0 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
101b0 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
101c0 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
101d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
101e0 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
101f0 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
10200 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
10210 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
10220 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
10230 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10240 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
10250 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
10260 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
10270 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
10280 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
10290 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
102a0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
102b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
102c0 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
102d0 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
102e0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
102f0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
10300 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
10310 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10320 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
10330 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
10340 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
10350 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
10360 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
10370 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
10380 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
10390 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
103a0 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
103b0 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
103c0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
103d0 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
103e0 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
103f0 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
10400 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
10410 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
10420 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
10430 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10440 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
10450 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
10460 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
10470 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
10480 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
10490 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
104a0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
104b0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
104c0 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
104d0 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
104e0 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
104f0 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
10500 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
10510 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
10520 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
10530 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
10540 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
10550 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
10560 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
10570 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
10580 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
10590 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
105a0 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
105b0 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
105c0 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
105d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
105e0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
105f0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
10600 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
10610 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
10620 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
10630 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
10640 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
10650 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
10660 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
10670 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10680 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
10690 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
106a0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
106b0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
106c0 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
106d0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
106e0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
106f0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
10700 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
10710 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
10720 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
10730 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
10740 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
10750 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
10760 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
10770 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
10780 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
10790 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
107a0 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
107b0 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
107c0 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
107d0 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
107e0 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
107f0 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
10800 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
10810 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
10820 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
10830 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
10840 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
10850 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10860 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
10870 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
10880 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
10890 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
108a0 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
108b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
108c0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
108d0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
108e0 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
108f0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
10900 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
10910 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
10920 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
10930 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lure..*/.SQLITE_
10940 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
10950 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
10960 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
10970 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10980 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  n(void);.SQLITE_
10990 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
109a0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53  os_init(void);.S
109b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
109c0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
109d0 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
109e0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
109f0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
10a00 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
10a10 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10a20 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
10a30 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
10a40 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10a50 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
10a60 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
10a70 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
10a80 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
10a90 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
10aa0 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
10ab0 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
10ac0 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
10ad0 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
10ae0 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
10af0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
10b00 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
10b10 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
10b20 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
10b30 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
10b40 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
10b50 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
10b60 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65  ** <b>The sqlite
10b70 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
10b80 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
10b90 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c  adsafe. The appl
10ba0 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
10bb0 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  ensure that no o
10bc0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
10bd0 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
10be0 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
10bf0 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
10c00 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
10c10 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a   running.</b>.**
10c20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10c30 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
10c40 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ce.** may only b
10c50 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
10c60 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
10c70 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
10c80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
10c90 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
10ca0 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
10cb0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10cc0 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
10cd0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10ce0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
10cf0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10d00 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
10d10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
10d20 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
10d30 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
10d40 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
10d50 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
10d60 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
10d70 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
10d80 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
10d90 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
10da0 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
10db0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
10dc0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
10dd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
10de0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
10df0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
10e00 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
10e10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10e20 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
10e30 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
10e40 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
10e50 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
10e60 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
10e70 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
10e80 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10e90 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
10ea0 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
10eb0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10ec0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
10ed0 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
10ee0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
10ef0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10f00 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
10f10 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
10f20 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
10f30 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
10f40 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
10f50 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
10f60 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
10f70 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
10f80 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
10f90 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
10fa0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
10fb0 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
10fc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10fd0 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
10fe0 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d  connections.** M
10ff0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
11000 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
11010 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
11020 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
11030 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
11040 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
11050 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
11060 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
11070 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
11080 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
11090 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
110a0 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
110b0 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
110c0 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
110d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
110e0 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
110f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11100 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
11110 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
11120 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
11130 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
11140 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11150 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
11160 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
11170 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
11180 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
11190 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
111a0 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
111b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
111c0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
111d0 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
111e0 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
111f0 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
11200 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
11210 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
11220 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
11230 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
11240 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
11250 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
11260 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
11270 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
11280 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  essful..*/.SQLIT
11290 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
112a0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
112b0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
112c0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
112d0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
112e0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
112f0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
11300 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11310 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
11320 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
11330 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
11340 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
11350 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
11360 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
11370 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
11380 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
11390 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
113a0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
113b0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
113c0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
113d0 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
113e0 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
113f0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
11400 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
11410 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
11420 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11430 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
11440 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
11450 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
11460 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
11470 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11480 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
11490 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
114a0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
114b0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
114c0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
114d0 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
114e0 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
114f0 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
11500 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
11510 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
11520 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
11530 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
11540 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
11550 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
11560 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
11570 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
11580 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
11590 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
115a0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
115b0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
115c0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
115d0 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
115e0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
115f0 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
11600 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
11610 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
11620 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
11630 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
11640 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
11650 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11660 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
11670 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
11680 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
11690 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
116a0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
116b0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
116c0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
116d0 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
116e0 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
116f0 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
11700 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
11710 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
11720 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
11730 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
11740 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
11750 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
11760 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
11770 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
11780 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
11790 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
117a0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
117b0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
117c0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
117d0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
117e0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
117f0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
11800 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11810 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
11820 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
11830 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
11840 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
11850 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
11860 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
11870 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
11880 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
11890 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
118a0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
118b0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
118c0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
118d0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
118e0 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
118f0 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
11900 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
11910 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
11920 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
11930 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
11940 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
11950 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
11960 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
11970 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
11980 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
11990 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
119a0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
119b0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
119c0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
119d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
119e0 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
119f0 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
11a00 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
11a10 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
11a20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
11a30 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
11a40 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
11a50 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
11a60 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
11a70 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
11a80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11a90 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
11aa0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
11ab0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
11ac0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
11ad0 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
11ae0 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
11af0 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
11b00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
11b10 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
11b20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
11b30 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
11b40 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
11b50 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
11b60 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
11b70 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
11b80 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
11b90 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
11ba0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
11bb0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
11bc0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
11bd0 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
11be0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
11bf0 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
11c00 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
11c10 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
11c20 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
11c30 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
11c40 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
11c50 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
11c60 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
11c70 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
11c80 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
11c90 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
11ca0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
11cb0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
11cc0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
11cd0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
11ce0 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
11cf0 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
11d00 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
11d10 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
11d20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
11d30 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
11d40 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
11d50 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
11d60 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
11d70 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
11d80 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
11d90 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
11da0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
11db0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
11dc0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
11dd0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
11de0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11df0 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
11e00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
11e10 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
11e20 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
11e30 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
11e40 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
11e50 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
11e60 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
11e70 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
11e80 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
11e90 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
11ea0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
11eb0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
11ec0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
11ed0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
11ee0 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
11ef0 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
11f00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
11f10 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
11f20 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
11f30 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
11f40 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
11f50 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
11f60 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
11f70 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
11f80 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
11f90 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11fa0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
11fb0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
11fc0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
11fd0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
11fe0 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
11ff0 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
12000 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
12010 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
12020 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
12030 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
12040 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
12050 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
12060 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
12070 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12080 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
12090 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
120a0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
120b0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
120c0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
120d0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
120e0 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
120f0 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
12100 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
12110 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
12120 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
12130 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
12140 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
12150 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
12160 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
12170 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
12180 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
12190 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
121a0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
121b0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
121c0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
121d0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
121e0 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
121f0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
12200 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
12210 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
12220 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
12230 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
12240 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
12250 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
12260 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
12270 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12280 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
12290 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
122a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
122b0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
122c0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
122d0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
122e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
122f0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
12300 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
12310 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
12320 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
12330 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12340 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
12350 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
12360 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
12370 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
12380 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
12390 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
123a0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
123b0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
123c0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
123d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
123e0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
123f0 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
12400 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
12410 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
12420 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
12430 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12440 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
12450 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
12460 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12470 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
12480 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12490 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
124a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
124b0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
124c0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
124d0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
124e0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
124f0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
12500 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
12510 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12520 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
12530 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
12540 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
12550 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
12560 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
12570 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
12580 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
12590 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
125a0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
125b0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
125c0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
125d0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
125e0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
125f0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12600 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
12610 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
12620 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
12630 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
12640 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
12650 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
12660 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12670 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
12680 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
12690 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
126a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
126b0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
126c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
126d0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
126e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
126f0 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
12700 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12710 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
12720 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12730 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
12740 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
12750 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
12760 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
12770 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
12780 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
12790 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
127a0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
127b0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
127c0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
127d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
127e0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
127f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
12800 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
12810 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
12820 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
12830 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12840 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12850 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
12860 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
12870 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
12880 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
12890 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
128a0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
128b0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
128c0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
128d0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
128e0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
128f0 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
12900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12910 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
12920 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
12930 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12940 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12950 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12960 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12970 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12980 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
12990 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
129a0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
129b0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
129c0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
129d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
129e0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
129f0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12a00 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12a10 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12a20 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
12a30 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12a40 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
12a50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
12a60 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
12a70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12a80 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
12a90 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12aa0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12ab0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12ac0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12ad0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12ae0 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
12af0 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
12b00 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
12b10 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
12b20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
12b30 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
12b40 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
12b50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12b60 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
12b70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
12b80 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
12b90 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
12ba0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
12bb0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12bc0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
12bd0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
12be0 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
12bf0 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
12c00 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
12c10 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
12c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
12c30 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12c40 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
12c50 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
12c60 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
12c70 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
12c80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12c90 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
12ca0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
12cb0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
12cc0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
12cd0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
12ce0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12cf0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12d00 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12d10 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12d20 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12d30 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12d40 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
12d50 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
12d60 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
12d70 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
12d80 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12d90 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12da0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12db0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12dc0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12dd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12de0 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
12df0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12e00 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12e10 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12e20 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12e30 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
12e40 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
12e50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12e60 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
12e70 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12e80 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
12e90 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12ea0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12eb0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12ec0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
12ed0 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
12ee0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
12ef0 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
12f00 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
12f10 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
12f20 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
12f30 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
12f40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12f50 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
12f60 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
12f70 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
12f80 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
12f90 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
12fa0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12fb0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12fc0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
12fd0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
12fe0 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
12ff0 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
13000 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13010 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
13020 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13030 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
13040 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13050 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13060 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
13070 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13080 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
13090 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
130a0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
130b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
130c0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
130d0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
130e0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
130f0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
13100 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
13110 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
13120 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13130 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
13140 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13150 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13160 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
13170 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13180 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
13190 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
131a0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
131b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
131c0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
131d0 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
131e0 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
131f0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13200 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13210 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
13220 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
13230 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
13240 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
13250 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
13260 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
13270 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
13280 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
13290 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
132a0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
132b0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
132c0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
132d0 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
132e0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
132f0 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
13300 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
13310 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
13320 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
13330 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
13340 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
13350 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
13360 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
13370 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
13380 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
13390 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
133a0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
133b0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
133c0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
133d0 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
133e0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
133f0 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
13400 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
13410 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
13420 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
13430 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
13440 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
13450 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
13460 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
13470 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
13480 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
13490 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
134a0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
134b0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
134c0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
134d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
134e0 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
134f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13500 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
13510 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
13520 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
13530 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13540 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13550 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
13560 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
13570 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  or scratch memor
13580 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20  y.  ^(There are 
13590 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a  three arguments.
135a0 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ** to SQLITE_CON
135b0 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20  FIG_SCRATCH:  A 
135c0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
135d0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
135e0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
135f0 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
13600 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
13610 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
13620 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
13630 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13640 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
13650 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
13660 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
13670 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29  llocations (N).)
13680 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ^.** The first a
13690 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
136a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
136b0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
136c0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
136d0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
136e0 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
136f0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75  QLite will not u
13700 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  se more than one
13710 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
13720 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20   per thread..** 
13730 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
13740 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72  er request a scr
13750 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
13760 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
13770 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
13780 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
13790 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  .** ^If SQLite n
137a0 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
137b0 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
137c0 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
137d0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
137e0 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
137f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
13800 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
13810 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
13820 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
13830 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
13840 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20  ed.<p>.** ^When 
13850 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
13860 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f  provides any amo
13870 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d  unt of scratch m
13880 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53  emory using.** S
13890 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
138a0 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f  ATCH, SQLite avo
138b0 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20  ids unnecessary 
138c0 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  large.** [sqlite
138d0 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c  3_malloc|heap al
138e0 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  locations]..** T
138f0 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f  his can help [Ro
13900 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65  bson proof|preve
13910 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  nt memory alloca
13920 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64  tion failures] d
13930 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72  ue to heap.** fr
13940 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c  agmentation in l
13950 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64  ow-memory embedd
13960 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c  ed systems..** <
13970 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13980 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13990 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
139a0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
139b0 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
139c0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
139d0 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
139e0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
139f0 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74  memory pool.** t
13a00 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
13a10 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
13a20 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
13a30 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
13a40 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
13a50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
13a60 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
13a70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
13a80 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70  a no-op if an ap
13a90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
13aa0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
13ab0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
13ac0 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
13ad0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
13ae0 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54  _PCACHE2]..** ^T
13af0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
13b00 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
13b10 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13b20 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
13b30 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
13b40 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d  ned memory (pMem
13b50 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  ), the size of e
13b60 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c  ach page cache l
13b70 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ine (sz),.** and
13b80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
13b90 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a  ache lines (N)..
13ba0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
13bb0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
13bc0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
13bd0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
13be0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
13bf0 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
13c00 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
13c10 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
13c20 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
13c30 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
13c40 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
13c50 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
13c60 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
13c70 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
13c80 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51  rmined using [SQ
13c90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13ca0 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49  HE_HDRSZ]..** ^I
13cb0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
13cc0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
13cd0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
13ce0 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
13cf0 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
13d00 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
13d10 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61  .  The pMem.** a
13d20 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
13d30 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
13d40 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74  inter or a point
13d50 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  er to an 8-byte.
13d60 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  ** aligned block
13d70 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74   of memory of at
13d80 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
13d90 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  s, otherwise.** 
13da0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
13db0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
13dc0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20  ..** ^When pMem 
13dd0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
13de0 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20  ite will strive 
13df0 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  to use the memor
13e00 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f  y provided.** to
13e10 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61   satisfy page ca
13e20 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69  che needs, falli
13e30 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69  ng back to [sqli
13e40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66  te3_malloc()] if
13e50 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65  .** a page cache
13e60 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20   line is larger 
13e70 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72  than sz bytes or
13e80 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70   if all of the p
13e90 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  Mem buffer.** is
13ea0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
13eb0 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20  If pMem is NULL 
13ec0 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72  and N is non-zer
13ed0 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74  o, then each dat
13ee0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13ef0 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74  .** does an init
13f00 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74  ial bulk allocat
13f10 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63  ion for page cac
13f20 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f  he memory.** fro
13f30 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
13f40 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20  c()] sufficient 
13f50 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65  for N cache line
13f60 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  s if N is positi
13f70 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32  ve or.** of -102
13f80 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69  4*N bytes if N i
13f90 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49  s negative, . ^I
13fa0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
13fb0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13fc0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
13fd0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
13fe0 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69  ded by the initi
13ff0 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  al.** allocation
14000 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f  , then SQLite go
14010 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
14020 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74  alloc()] separat
14030 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ely for each.** 
14040 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65  additional cache
14050 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   line. </dd>.**.
14060 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14070 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
14080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14090 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
140a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
140b0 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
140c0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
140d0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
140e0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
140f0 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
14100 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
14110 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14120 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
14130 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
14140 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
14150 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
14160 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  d.** [SQLITE_CON
14170 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
14180 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
14190 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
141a0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
141b0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
141c0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
141d0 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
141e0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
141f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
14200 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
14210 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
14220 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
14230 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
14240 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
14250 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
14260 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14270 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
14280 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
14290 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
142a0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
142b0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
142c0 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
142d0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
142e0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
142f0 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
14300 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
14310 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
14320 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
14330 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
14340 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
14350 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
14360 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
14370 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
14380 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
14390 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
143a0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
143b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
143c0 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
143d0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
143e0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
143f0 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
14400 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14410 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
14420 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
14430 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
14440 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
14450 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
14460 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14470 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
14480 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
14490 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
144a0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
144b0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
144c0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
144d0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
144e0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
144f0 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
14500 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
14510 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
14520 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
14530 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
14540 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
14550 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
14560 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14570 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
14580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14590 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
145a0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
145b0 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
145c0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
145d0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
145e0 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
145f0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
14600 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
14610 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14620 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
14630 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
14640 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
14650 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
14660 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
14670 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
14680 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
14690 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
146a0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
146b0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
146c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
146d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
146e0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
146f0 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
14700 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
14710 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
14720 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
14730 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14740 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14750 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
14760 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14770 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
14780 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
14790 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
147a0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
147b0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
147c0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
147d0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
147e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
147f0 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
14800 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
14810 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14820 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
14830 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
14840 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
14850 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14860 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
14870 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14880 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
14890 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
148a0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
148b0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
148c0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
148d0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
148e0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
148f0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
14900 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
14910 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
14920 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
14930 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
14940 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
14950 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
14960 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
14970 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
14980 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
14990 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
149a0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
149b0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
149c0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
149d0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
149e0 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
149f0 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
14a00 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
14a10 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
14a20 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
14a30 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14a40 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14a50 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14a60 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14a70 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14a80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14a90 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
14aa0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
14ab0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
14ac0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
14ad0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
14ae0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
14af0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
14b00 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
14b10 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
14b20 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
14b30 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
14b40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
14b50 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14b60 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14b70 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
14b80 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14b90 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
14ba0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14bb0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
14bc0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
14bd0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
14be0 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
14bf0 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
14c00 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
14c10 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
14c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
14c30 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
14c40 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
14c50 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
14c60 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
14c70 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
14c80 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
14c90 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
14ca0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
14cb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
14cc0 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
14cd0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
14ce0 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
14cf0 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
14d00 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
14d10 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
14d20 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
14d30 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
14d40 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
14d50 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
14d60 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
14d70 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
14d80 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
14d90 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
14da0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14db0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14dc0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
14dd0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
14de0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14df0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14e00 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14e10 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14e20 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
14e30 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
14e40 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14e50 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14e60 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
14e70 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
14e80 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
14e90 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
14ea0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14eb0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
14ec0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
14ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
14ee0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14ef0 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
14f00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14f10 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
14f20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14f30 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
14f40 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14f50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14f60 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
14f70 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14f80 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14f90 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14fa0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14fb0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14fc0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
14fd0 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
14fe0 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
14ff0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
15000 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
15010 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
15020 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15030 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
15040 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
15050 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
15060 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
15070 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
15080 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
15090 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
150a0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
150b0 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
150c0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
150d0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
150e0 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
150f0 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
15100 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
15110 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
15120 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
15130 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
15140 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
15150 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
15160 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
15170 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
15180 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
15190 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
151a0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
151b0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
151c0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
151d0 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
151e0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
151f0 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
15200 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
15210 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
15220 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
15230 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15240 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
15250 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
15260 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
15270 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
15280 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
15290 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
152a0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
152b0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
152c0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
152d0 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
152e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
152f0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
15300 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
15310 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
15320 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
15330 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
15340 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
15350 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
15360 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
15370 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
15380 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
15390 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
153a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
153b0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
153c0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
153d0 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
153e0 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
153f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
15400 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
15410 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
15420 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
15430 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
15440 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
15450 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
15460 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
15470 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
15480 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
15490 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
154a0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
154b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
154c0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
154d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
154e0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
154f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15500 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
15510 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15520 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
15530 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15540 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
15550 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15560 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
15570 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
15580 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
15590 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
155a0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
155b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
155c0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
155d0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
155e0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
155f0 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
15600 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
15610 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
15620 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
15630 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
15640 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
15650 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
15660 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
15670 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
15680 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
15690 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
156a0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
156b0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
156c0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
156d0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
156e0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
156f0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
15700 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
15710 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
15720 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
15730 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
15740 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
15750 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
15760 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
15770 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
15780 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
15790 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
157a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
157b0 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
157c0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
157d0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
157e0 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
157f0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
15800 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
15810 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
15820 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
15830 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
15840 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
15850 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15860 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15870 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
15880 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
15890 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
158a0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
158b0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
158c0 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
158d0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
158e0 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
158f0 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
15900 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
15910 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
15920 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
15930 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
15940 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15950 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15960 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
15970 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
15980 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
15990 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
159a0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
159b0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
159c0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
159d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
159e0 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
159f0 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
15a00 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15a10 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
15a20 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
15a30 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
15a40 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
15a50 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
15a60 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
15a70 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
15a80 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
15a90 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
15aa0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
15ab0 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
15ac0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
15ad0 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
15ae0 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
15af0 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
15b00 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
15b10 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
15b20 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
15b30 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
15b40 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
15b50 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
15b60 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
15b70 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
15b80 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15b90 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
15ba0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
15bb0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15bc0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
15bd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15be0 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
15bf0 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
15c00 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
15c10 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
15c20 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
15c30 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
15c40 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
15c50 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
15c60 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
15c70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
15c80 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15c90 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
15ca0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15cb0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
15cc0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
15cd0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
15ce0 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
15cf0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
15d00 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
15d10 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
15d20 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
15d30 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
15d40 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
15d50 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
15d60 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
15d70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
15d80 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
15d90 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
15da0 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
15db0 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
15dc0 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
15dd0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
15de0 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
15df0 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
15e00 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
15e10 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
15e20 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
15e30 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
15e40 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
15e50 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
15e60 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
15e70 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15e80 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
15e90 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
15ea0 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
15eb0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
15ec0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
15ed0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
15ee0 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
15ef0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
15f00 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
15f10 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
15f20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15f30 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
15f40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
15f50 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
15f60 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
15f70 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
15f80 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
15f90 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15fa0 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
15fb0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
15fc0 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
15fd0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
15fe0 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
15ff0 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
16000 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16010 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
16020 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
16030 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
16040 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
16050 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
16060 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
16070 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
16080 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
16090 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
160a0 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
160b0 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
160c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
160d0 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
160e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
160f0 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
16100 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
16110 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
16120 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
16130 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
16140 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
16150 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
16160 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
16170 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
16180 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
16190 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
161a0 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
161b0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
161c0 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
161d0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
161e0 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
161f0 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
16200 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16210 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
16220 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
16230 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
16240 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
16250 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
16260 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
16270 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
16280 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
16290 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
162a0 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
162b0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
162c0 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
162d0 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
162e0 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
162f0 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
16300 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
16310 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
16320 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
16330 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16340 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
16350 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
16360 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
16370 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
16380 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
16390 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
163a0 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
163b0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
163c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
163d0 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
163e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
163f0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
16400 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
16410 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
16420 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
16430 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
16440 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
16450 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
16460 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
16470 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
16480 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
16490 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
164a0 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
164b0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
164c0 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
164d0 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
164e0 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
164f0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
16500 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
16510 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
16520 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  eap..**.** [[SQL
16530 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16540 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  E_HDRSZ]].** <dt
16550 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
16560 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c  CACHE_HDRSZ.** <
16570 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16580 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
16590 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
165a0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
165b0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
165c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
165d0 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65  nteger and write
165e0 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  s into that inte
165f0 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ger the number o
16600 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73  f extra.** bytes
16610 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72   per page requir
16620 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65  ed for each page
16630 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   in [SQLITE_CONF
16640 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
16650 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * The amount of 
16660 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75  extra space requ
16670 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20  ired can change 
16680 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
16690 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61   compiler,.** ta
166a0 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61  rget platform, a
166b0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
166c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
166d0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d  E_CONFIG_PMASZ]]
166e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
166f0 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c  ONFIG_PMASZ.** <
16700 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16710 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69  ONFIG_PMASZ opti
16720 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16730 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
16740 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67  h.** is an unsig
16750 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
16760 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75  sets the "Minimu
16770 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20  m PMA Size" for 
16780 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65  the multithreade
16790 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74  d.** sorter to t
167a0 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68  hat integer.  Th
167b0 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75  e default minimu
167c0 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65  m PMA Size is se
167d0 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
167e0 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a  ITE_SORTER_PMASZ
167f0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16800 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65  ption.  New thre
16810 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64  ads are launched
16820 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68  .** to help with
16830 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73   sort operations
16840 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61   when multithrea
16850 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69  ded sorting.** i
16860 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67  s enabled (using
16870 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72   the [PRAGMA thr
16880 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61  eads] command) a
16890 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  nd the amount of
168a0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62   content.** to b
168b0 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73  e sorted exceeds
168c0 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74   the page size t
168d0 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  imes the minimum
168e0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47   of the.** [PRAG
168f0 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73  MA cache_size] s
16900 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20  etting and this 
16910 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  value..**.** [[S
16920 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16930 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a  TJRNL_SPILL]].**
16940 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16950 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16960 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  L.** <dd>^The SQ
16970 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16980 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f  JRNL_SPILL optio
16990 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
169a0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
169b0 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20  .** becomes the 
169c0 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [statement journ
169d0 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73  al] spill-to-dis
169e0 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a  k threshold.  .*
169f0 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75  * [Statement jou
16a00 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20  rnals] are held 
16a10 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20  in memory until 
16a20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62  their size (in b
16a30 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73  ytes).** exceeds
16a40 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c   this threshold,
16a50 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20   at which point 
16a60 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e  they are written
16a70 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20   to disk..** Or 
16a80 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64  if the threshold
16a90 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e   is -1, statemen
16aa0 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61  t journals are a
16ab0 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78  lways held.** ex
16ac0 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d  clusively in mem
16ad0 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61  ory..** Since ma
16ae0 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  ny statement jou
16af0 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f  rnals never beco
16b00 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e  me large, settin
16b10 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74  g the spill.** t
16b20 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61  hreshold to a va
16b30 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69  lue such as 64Ki
16b40 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65  B can greatly re
16b50 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20  duce the amount 
16b60 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72  of.** I/O requir
16b70 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74  ed to support st
16b80 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b  atement rollback
16b90 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
16ba0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20   value for this 
16bb0 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72  setting is contr
16bc0 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  olled by the.** 
16bd0 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c  [SQLITE_STMTJRNL
16be0 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d  _SPILL] compile-
16bf0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
16c00 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
16c10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16c20 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
16c30 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16c40 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16c50 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
16c60 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16c70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16c80 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
16c90 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16ca0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16cb0 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
16cc0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
16cd0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
16ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16cf0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
16d00 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
16d10 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16d20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16d30 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
16d40 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
16d50 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
16d60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16d70 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
16d80 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
16d90 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
16da0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16db0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
16dc0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
16dd0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
16de0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
16df0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16e00 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
16e10 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
16e20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16e30 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
16e40 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
16e50 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
16e60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e70 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
16e80 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
16e90 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16ea0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
16eb0 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
16ec0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
16ed0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
16ee0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
16ef0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16f00 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
16f10 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
16f20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16f30 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
16f40 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
16f50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16f60 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16f70 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
16f80 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
16f90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
16fa0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
16fb0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
16fc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16fd0 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
16fe0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
16ff0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17000 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
17010 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
17020 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
17030 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
17040 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17050 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
17060 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
17070 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
17080 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17090 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
170a0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
170b0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
170c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
170d0 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
170e0 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
170f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17100 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
17110 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
17120 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
17130 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
17140 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17150 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
17160 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
17170 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
17180 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17190 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
171a0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
171b0 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
171c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
171d0 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
171e0 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
171f0 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65  int szPma */.#de
17200 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17210 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
17220 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e  L      26  /* in
17230 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a  t nByte */../*.*
17240 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
17250 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
17260 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
17270 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
17280 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
17290 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
172a0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
172b0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
172c0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
172d0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
172e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
172f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17300 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
17310 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
17320 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
17330 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
17340 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
17350 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
17360 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
17370 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
17380 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
17390 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
173a0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
173b0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
173c0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
173d0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
173e0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
173f0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
17400 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
17410 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17420 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
17430 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
17440 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
17450 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
17460 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
17470 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
17480 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
17490 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
174a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
174b0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
174c0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
174d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
174e0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
174f0 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
17500 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
17510 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
17520 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
17530 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
17540 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
17550 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
17560 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
17570 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
17580 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
17590 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
175a0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
175b0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
175c0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
175d0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
175e0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
175f0 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
17600 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
17610 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
17620 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
17630 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
17640 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
17650 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
17660 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
17670 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
17680 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
17690 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
176a0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
176b0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
176c0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
176d0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
176e0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
176f0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
17700 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
17710 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
17720 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
17730 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
17740 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
17750 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
17760 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
17770 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
17780 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
17790 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
177a0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
177b0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
177c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
177d0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
177e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
177f0 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
17800 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
17810 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
17820 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
17830 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
17840 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
17850 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
17860 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
17870 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
17880 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17890 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
178a0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
178b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
178c0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
178d0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
178e0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
178f0 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
17900 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
17910 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
17920 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
17930 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
17940 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17950 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
17960 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
17970 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
17980 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
17990 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
179a0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
179b0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
179c0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
179d0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
179e0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
179f0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
17a00 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
17a10 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
17a20 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
17a30 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
17a40 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
17a50 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
17a60 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
17a70 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
17a80 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
17a90 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
17aa0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
17ab0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
17ac0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
17ad0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
17ae0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
17af0 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
17b00 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
17b10 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
17b20 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17b30 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
17b40 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
17b50 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
17b60 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17b70 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
17b80 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17b90 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
17ba0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
17bb0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
17bc0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
17bd0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
17be0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
17bf0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17c00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17c10 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17c20 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17c30 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
17c40 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
17c50 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17c60 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17c70 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17c80 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17c90 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
17ca0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17cb0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17cc0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17cd0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
17ce0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
17cf0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17d00 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17d10 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17d20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17d30 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17d40 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17d50 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
17d60 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
17d70 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
17d80 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
17d90 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
17da0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
17db0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17dc0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17dd0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17de0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17df0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17e00 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17e10 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
17e20 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
17e30 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
17e40 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
17e50 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
17e60 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
17e70 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
17e80 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
17e90 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
17ea0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
17eb0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
17ec0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17ed0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
17ee0 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENIZER</dt>.** <
17ef0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17f00 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17f10 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
17f20 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a  e two-argument.*
17f30 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  * version of the
17f40 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72   [fts3_tokenizer
17f50 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69  ()] function whi
17f60 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  ch is part of th
17f70 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c  e.** [FTS3] full
17f80 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67  -text search eng
17f90 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a  ine extension..*
17fa0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
17fb0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17fc0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
17fd0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17fe0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
17ff0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18000 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  sable fts3_token
18010 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73  izer() or.** pos
18020 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
18030 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
18040 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
18050 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
18060 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a  g.** unchanged..
18070 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
18080 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
18090 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
180a0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
180b0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
180c0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
180d0 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65  hether fts3_toke
180e0 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  nizer is disable
180f0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
18100 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18110 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18120 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
18130 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18140 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
18150 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
18160 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18170 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
18180 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18190 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
181a0 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f  LOAD_EXTENSION</
181b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
181c0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
181d0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
181e0 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  sable the [sqlit
181f0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
18200 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  n()].** interfac
18210 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20  e independently 
18220 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74  of the [load_ext
18230 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75  ension()] SQL fu
18240 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b  nction..** The [
18250 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
18260 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18270 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20   API enables or 
18280 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68  disables both th
18290 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69  e.** C-API [sqli
182a0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
182b0 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51  on()] and the SQ
182c0 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64  L function [load
182d0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a  _extension()]..*
182e0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
182f0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18300 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57   arguments..** W
18310 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72  hen the first ar
18320 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69  gument to this i
18330 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74  nterface is 1, t
18340 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41  hen only the C-A
18350 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  PI is.** enabled
18360 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
18370 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69  ction remains di
18380 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20  sabled.  If the 
18390 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
183a0 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66  o.** this interf
183b0 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62  ace is 0, then b
183c0 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e  oth the C-API an
183d0 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
183e0 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e  on are disabled.
183f0 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74  .** If the first
18400 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c   argument is -1,
18410 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73   then no changes
18420 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61   are made to sta
18430 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65  te of either the
18440 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65  .** C-API or the
18450 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
18460 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
18470 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
18480 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
18490 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
184a0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
184b0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
184c0 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c  ether [sqlite3_l
184d0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
184e0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
184f0 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18500 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  bled following t
18510 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
18520 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18530 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c  may.** be a NULL
18540 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69   pointer, in whi
18550 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20  ch case the new 
18560 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
18570 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a  eported back..**
18580 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
18590 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
185a0 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e  _MAINDBNAME</dt>
185b0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
185c0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
185d0 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65   change the name
185e0 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64   of the "main" d
185f0 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d  atabase.** schem
18600 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72  a.  ^The sole ar
18610 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
18620 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e  ter to a constan
18630 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a  t UTF8 string.**
18640 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f   which will beco
18650 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d  me the new schem
18660 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20  a name in place 
18670 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c  of "main".  ^SQL
18680 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ite.** does not 
18690 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
186a0 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65  he new main sche
186b0 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20  ma name string, 
186c0 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  so the applicati
186d0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72  on.** must ensur
186e0 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d  e that the argum
186f0 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ent passed into 
18700 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70  this DBCONFIG op
18710 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65  tion is unchange
18720 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72  d.** until after
18730 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18740 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
18750 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
18760 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18770 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
18780 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LOSE</dt>.** <dd
18790 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20  > Usually, when 
187a0 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61  a database in wa
187b0 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64  l mode is closed
187c0 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f   or detached fro
187d0 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  m a .** database
187e0 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20   handle, SQLite 
187f0 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77  checks if this w
18800 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68  ill mean that th
18810 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a  ere are now no .
18820 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61  ** connections a
18830 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74  t all to the dat
18840 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74  abase. If so, it
18850 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63   performs a chec
18860 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61  kpoint .** opera
18870 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73  tion before clos
18880 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  ing the connecti
18890 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  on. This option 
188a0 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a  may be used to.*
188b0 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20  * override this 
188c0 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66  behaviour. The f
188d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70  irst parameter p
188e0 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70  assed to this op
188f0 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e  eration.** is an
18900 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a   integer - non-z
18910 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 63  ero to disable c
18920 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c  heckpoints-on-cl
18930 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68  ose, or zero (th
18940 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f  e.** default) to
18950 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 68   enable them. Th
18960 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18970 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18980 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
18990 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77   into which is w
189a0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
189b0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
189c0 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e  r checkpoints-on
189d0 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62  -close.** have b
189e0 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30  een disabled - 0
189f0 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74   if they are not
18a00 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20   disabled, 1 if 
18a10 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64  they are..** </d
18a20 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
18a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18a40 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
18a50 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
18a60 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68  1000 /* const ch
18a70 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ar* */.#define S
18a80 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18a90 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20  OOKASIDE        
18aa0 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69       1001 /* voi
18ab0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
18ac0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18ad0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
18ae0 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32  Y           1002
18af0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18b00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18b10 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
18b20 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30  RIGGER        10
18b30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  03 /* int int* *
18b40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18b50 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18b60 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20  _FTS3_TOKENIZER 
18b70 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1004 /* int int*
18b80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18b90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18ba0 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
18bb0 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e  N 1005 /* int in
18bc0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18bd0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
18be0 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20  _CKPT_ON_CLOSE  
18bf0 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20      1006 /* int 
18c00 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
18c10 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
18c20 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
18c30 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
18c40 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
18c50 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
18c60 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
18c70 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
18c80 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
18c90 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
18ca0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
18cb0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
18cc0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
18cd0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
18ce0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
18cf0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
18d00 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
18d10 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
18d20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
18d30 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
18d40 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
18d50 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
18d60 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
18d70 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
18d80 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45  sert Rowid.** ME
18d90 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
18da0 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
18db0 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74  in most SQLite t
18dc0 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f  ables (except fo
18dd0 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  r [WITHOUT ROWID
18de0 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73  ] tables).** has
18df0 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
18e00 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
18e10 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
18e20 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
18e30 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
18e40 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
18e50 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
18e60 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
18e70 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
18e80 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
18e90 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
18ea0 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
18eb0 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
18ec0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
18ed0 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
18ee0 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
18ef0 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
18f00 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
18f10 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
18f20 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
18f30 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
18f40 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
18f50 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  he sqlite3_last_
18f60 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
18f70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
18f80 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
18f90 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65   the .** most re
18fa0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
18fb0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
18fc0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
18fd0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
18fe0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
18ff0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e  nnection D..** ^
19000 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
19010 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
19020 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f  les are not reco
19030 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  rded..** ^If no 
19040 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
19050 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
19060 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65  tables.** have e
19070 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
19080 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19090 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74  nection D, .** t
190a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  hen sqlite3_last
190b0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
190c0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
190d0 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
190e0 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
190f0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
19100 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
19110 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
19120 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
19130 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
19140 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
19150 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
19160 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
19170 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
19180 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
19190 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
191a0 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
191b0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
191c0 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
191d0 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
191e0 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
191f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
19200 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
19210 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
19220 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
19230 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
19240 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
19250 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
19260 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
19270 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
19280 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
19290 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
192a0 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
192b0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
192c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
192d0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
192e0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
192f0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
19300 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
19310 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
19320 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
19330 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
19340 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
19350 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
19360 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
19370 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
19380 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
19390 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
193a0 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
193b0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
193c0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
193d0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
193e0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
193f0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
19400 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
19410 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
19420 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
19430 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
19440 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
19450 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
19460 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
19470 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
19480 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
19490 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
194a0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
194b0 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
194c0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
194d0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
194e0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
194f0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
19500 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
19510 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
19520 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
19530 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
19540 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
19550 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19560 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
19570 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
19580 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
19590 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
195a0 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
195b0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
195c0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
195d0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
195e0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
195f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
19600 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
19610 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
19620 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
19630 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
19640 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
19650 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
19660 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
19670 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
19680 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
19690 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
196a0 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
196b0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
196c0 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  id]..*/.SQLITE_A
196d0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
196e0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
196f0 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
19700 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
19710 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
19720 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
19730 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
19740 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
19750 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
19760 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
19770 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
19780 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  fied, inserted o
19790 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
197a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
197b0 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
197c0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
197d0 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
197e0 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  t on the databas
197f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
19800 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e  cified by the on
19810 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ly parameter..**
19820 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
19830 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
19840 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
19850 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
19860 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
19870 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
19880 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  on..**.** ^Only 
19890 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72  changes made dir
198a0 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53  ectly by the INS
198b0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
198c0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
198d0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
198e0 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68  d - auxiliary ch
198f0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
19900 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
19910 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a  | triggers], .**
19920 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
19930 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41  tions] or [REPLA
19940 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
19950 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f  esolution are no
19960 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
19970 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
19980 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
19990 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20  ercepted by .** 
199a0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
199b0 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46  ger | INSTEAD OF
199c0 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e   triggers] are n
199d0 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65  ot counted. ^The
199e0 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72   value .** retur
199f0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
19a00 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61  hanges() immedia
19a10 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e  tely after an IN
19a20 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19a30 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
19a40 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69  ment run on a vi
19a50 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  ew is always zer
19a60 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  o. Only changes 
19a70 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a  made to real .**
19a80 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e   tables are coun
19a90 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67  ted..**.** Thing
19aa0 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c  s are more compl
19ab0 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71  icated if the sq
19ac0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
19ad0 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65  function is.** e
19ae0 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20  xecuted while a 
19af0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
19b00 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73  is running. This
19b10 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74   may happen if t
19b20 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  he.** program us
19b30 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  es the [changes(
19b40 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c  ) SQL function],
19b50 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65   or if some othe
19b60 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  r callback.** fu
19b70 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73  nction invokes s
19b80 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19b90 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e   directly. Essen
19ba0 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c  tially:.** .** <
19bb0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ul>.**   <li> ^(
19bc0 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20  Before entering 
19bd0 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
19be0 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  m the value retu
19bf0 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
19c00 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65    sqlite3_change
19c10 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  s() function is 
19c20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65  saved. After the
19c30 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19c40 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20   .**        has 
19c50 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72  finished, the or
19c60 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20  iginal value is 
19c70 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a  restored.)^.** .
19c80 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68  **   <li> ^(With
19c90 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  in a trigger pro
19ca0 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54  gram each INSERT
19cb0 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c  , UPDATE and DEL
19cc0 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73  ETE .**        s
19cd0 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68  tatement sets th
19ce0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19cf0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
19d00 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
19d10 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e   upon completion
19d20 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63   as normal. Of c
19d30 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75  ourse, this valu
19d40 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75  e will not inclu
19d50 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e  de .**        an
19d60 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72  y changes perfor
19d70 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67  med by sub-trigg
19d80 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69  ers, as the sqli
19d90 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
19da0 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77  *        value w
19db0 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64  ill be saved and
19dc0 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20   restored after 
19dd0 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72  each sub-trigger
19de0 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c   has run.)^.** <
19df0 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69  /ul>.** .** ^Thi
19e00 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20  s means that if 
19e10 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51  the changes() SQ
19e20 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73  L function (or s
19e30 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a  imilar) is used.
19e40 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
19e50 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
19e60 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
19e70 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
19e80 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75  ger, it .** retu
19e90 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73  rns the value as
19ea0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61   set when the ca
19eb0 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  lling statement 
19ec0 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e  began executing.
19ed0 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73  .** ^If it is us
19ee0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
19ef0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73   or subsequent s
19f00 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69  uch statement wi
19f10 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a  thin a trigger .
19f20 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20  ** program, the 
19f30 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72  value returned r
19f40 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62  eflects the numb
19f50 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
19f60 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70  ied by the .** p
19f70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20  revious INSERT, 
19f80 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
19f90 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
19fa0 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  n the same trigg
19fb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
19fc0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
19fd0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
19fe0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
19ff0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
1a000 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
1a010 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
1a020 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1a030 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1a040 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1a050 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1a060 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a070 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1a080 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a090 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1a0a0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1a0b0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
1a0c0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1a0d0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1a0e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1a0f0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a100 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1a110 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
1a120 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
1a130 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
1a140 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1a150 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1a160 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  n returns the to
1a170 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  tal number of ro
1a180 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64  ws inserted, mod
1a190 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  ified or.** dele
1a1a0 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45  ted by all [INSE
1a1b0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72  RT], [UPDATE] or
1a1c0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
1a1d0 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a  ents completed.*
1a1e0 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  * since the data
1a1f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a200 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c  was opened, incl
1a210 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63  uding those exec
1a220 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  uted as.** part 
1a230 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
1a240 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20  ams. ^Executing 
1a250 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1a260 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  f SQL statement.
1a270 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65  ** does not affe
1a280 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ct the value ret
1a290 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1a2a0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1a2b0 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65  ..** .** ^Change
1a2c0 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  s made as part o
1a2d0 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  f [foreign key a
1a2e0 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c  ctions] are incl
1a2f0 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63  uded in the.** c
1a300 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20  ount, but those 
1a310 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
1a320 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
1a330 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1a340 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67  e.** not. ^Chang
1a350 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
1a360 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
1a370 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20  d by INSTEAD OF 
1a380 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65  triggers .** are
1a390 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
1a3a0 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68   .** See also th
1a3b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1a3c0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1a3d0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1a3e0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1a3f0 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
1a400 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1a410 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1a420 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1a430 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1a440 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1a450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a460 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1a470 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1a480 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1a490 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
1a4a0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
1a4b0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1a4c0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1a4d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1a4e0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1a4f0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1a500 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a510 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
1a520 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
1a530 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  y.** METHOD: sql
1a540 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1a550 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
1a560 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
1a570 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
1a580 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
1a590 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
1a5a0 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
1a5b0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
1a5c0 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
1a5d0 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
1a5e0 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
1a5f0 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
1a600 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
1a610 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
1a620 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
1a630 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
1a640 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
1a650 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
1a660 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
1a670 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1a680 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
1a690 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
1a6a0 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
1a6b0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
1a6c0 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
1a6d0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1a6e0 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
1a6f0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
1a700 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1a710 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
1a720 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
1a730 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
1a740 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
1a750 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
1a760 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
1a770 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
1a780 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1a790 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
1a7a0 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
1a7b0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
1a7c0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
1a7d0 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
1a7e0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
1a7f0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
1a800 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
1a810 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
1a820 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
1a830 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
1a840 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
1a850 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
1a860 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1a870 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
1a880 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
1a890 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
1a8a0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
1a8b0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
1a8c0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
1a8d0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
1a8e0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
1a8f0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
1a900 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
1a910 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
1a920 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
1a930 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1a940 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a950 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
1a960 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
1a970 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1a980 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1a990 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
1a9a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
1a9b0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
1a9c0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1a9d0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1a9e0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1a9f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1aa00 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
1aa10 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
1aa20 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
1aa30 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
1aa40 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
1aa50 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
1aa60 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
1aa70 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
1aa80 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
1aa90 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
1aaa0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1aab0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1aac0 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
1aad0 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
1aae0 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
1aaf0 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
1ab00 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1ab10 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
1ab20 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
1ab30 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
1ab40 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
1ab50 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
1ab60 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1ab70 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
1ab80 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
1ab90 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
1aba0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1abb0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1abc0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1abd0 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
1abe0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
1abf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ac00 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
1ac10 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
1ac20 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
1ac30 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
1ac40 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
1ac50 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49   happen..*/.SQLI
1ac60 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
1ac70 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
1ac80 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1ac90 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
1aca0 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
1acb0 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
1acc0 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
1acd0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
1ace0 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
1acf0 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
1ad00 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
1ad10 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
1ad20 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
1ad30 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
1ad40 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1ad50 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
1ad60 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
1ad70 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
1ad80 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
1ad90 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
1ada0 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
1adb0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1adc0 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
1add0 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
1ade0 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
1adf0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1ae00 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
1ae10 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
1ae20 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
1ae30 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
1ae40 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
1ae50 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
1ae60 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
1ae70 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
1ae80 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
1ae90 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
1aea0 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
1aeb0 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
1aec0 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
1aed0 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
1aee0 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
1aef0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
1af00 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
1af10 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
1af20 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
1af30 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
1af40 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
1af50 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
1af60 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
1af70 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
1af80 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
1af90 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
1afa0 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
1afb0 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
1afc0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
1afd0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1afe0 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
1aff0 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
1b000 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
1b010 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1b020 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
1b030 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
1b040 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
1b050 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
1b060 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
1b070 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
1b080 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
1b090 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
1b0a0 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
1b0b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
1b0c0 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
1b0d0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
1b0e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
1b0f0 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
1b100 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
1b110 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b120 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
1b130 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
1b140 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
1b150 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
1b160 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b170 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
1b180 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
1b190 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
1b1a0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1b1b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1b1c0 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
1b1d0 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
1b1e0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1b1f0 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
1b200 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
1b210 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
1b220 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1b230 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
1b240 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1b250 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
1b260 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
1b270 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1b280 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
1b290 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1b2a0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1b2b0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
1b2c0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1b2d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1b2e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1b2f0 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
1b300 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  *sql);.SQLITE_AP
1b310 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
1b320 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
1b330 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
1b340 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
1b350 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
1b360 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
1b370 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20  _BUSY Errors.** 
1b380 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d  KEYWORDS: {busy-
1b390 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1b3a0 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d  } {busy handler}
1b3b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1b3c0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
1b3d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1b3e0 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69  ler(D,X,P) routi
1b3f0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
1b400 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  ck function X.**
1b410 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
1b420 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
1b430 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
1b440 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
1b450 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1b460 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1b470 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1b480 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1b490 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e  nnection] D when
1b4a0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
1b4b0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
1b4c0 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b  s the table lock
1b4d0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1b4e0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1b4f0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
1b500 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1b510 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
1b520 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64  y_timeout()] and
1b530 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1b540 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  meout]..**.** ^I
1b550 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1b560 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
1b570 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1b580 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1b590 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
1b5a0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
1b5b0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
1b5c0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
1b5d0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1b5e0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1b5f0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1b600 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
1b610 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1b620 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1b630 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
1b640 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
1b650 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
1b660 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
1b670 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1b680 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
1b690 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
1b6a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1b6b0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
1b6c0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1b6d0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
1b6e0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
1b6f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
1b700 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
1b710 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f  ed previously fo
1b720 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
1b730 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
1b740 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
1b750 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
1b760 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
1b770 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
1b780 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
1b790 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1b7a0 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
1b7b0 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74  is returned.** t
1b7c0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1b7d0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  n..** ^If the ca
1b7e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1b7f0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
1b800 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
1b810 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1b820 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1b830 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
1b840 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
1b850 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
1b860 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
1b870 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
1b880 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
1b890 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
1b8a0 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
1b8b0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
1b8c0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
1b8d0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
1b8e0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
1b8f0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
1b900 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
1b910 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
1b920 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
1b930 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65  _BUSY].** to the
1b940 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73   application ins
1b950 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
1b960 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61   the .** busy ha
1b970 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
1b980 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
1b990 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
1b9a0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
1b9b0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
1b9c0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
1b9d0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
1b9e0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
1b9f0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
1ba00 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1ba10 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
1ba20 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
1ba30 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
1ba40 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
1ba50 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
1ba60 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
1ba70 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
1ba80 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1ba90 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
1baa0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1bab0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
1bac0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
1bad0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1bae0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
1baf0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
1bb00 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
1bb10 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
1bb20 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
1bb30 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
1bb40 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
1bb50 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
1bb60 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
1bb70 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
1bb80 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
1bb90 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
1bba0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
1bbb0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
1bbc0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
1bbd0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
1bbe0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
1bbf0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
1bc00 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
1bc10 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
1bc20 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1bc30 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1bc40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
1bc50 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
1bc60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1bc70 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
1bc80 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
1bc90 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
1bca0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
1bcb0 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
1bcc0 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
1bcd0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1bce0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65  meout()].** or e
1bcf0 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d  valuating [PRAGM
1bd00 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e  A busy_timeout=N
1bd10 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68  ] will change th
1bd20 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65  e.** busy handle
1bd30 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72  r and thus clear
1bd40 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
1bd50 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  set busy handler
1bd60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
1bd70 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1bd80 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
1bd90 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
1bda0 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
1bdb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1bdc0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1bdd0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e  usy handler.  In
1bde0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
1bdf0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1be00 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  r is not reentra
1be10 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  nt.  Any such ac
1be20 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
1be30 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
1be40 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
1be50 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
1be60 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
1be70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1be80 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
1be90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1bea0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1beb0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
1bec0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1bed0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1bee0 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e  dler(sqlite3*,in
1bef0 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
1bf00 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1bf10 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
1bf20 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d  usy Timeout.** M
1bf30 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1bf40 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1bf50 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
1bf60 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
1bf70 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
1bf80 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
1bf90 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
1bfa0 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
1bfb0 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
1bfc0 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
1bfd0 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
1bfe0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
1bff0 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
1c000 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1c010 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
1c020 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
1c030 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
1c040 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1c050 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1c060 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
1c070 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
1c080 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
1c090 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
1c0a0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
1c0b0 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  USY]..**.** ^Cal
1c0c0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
1c0d0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
1c0e0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
1c0f0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
1c100 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
1c110 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
1c120 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1c130 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1c140 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
1c150 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
1c160 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1c170 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67  ection] at any g
1c180 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
1c190 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
1c1a0 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
1c1b0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
1c1c0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1c1d0 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
1c1e0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
1c1f0 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
1c200 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
1c210 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
1c220 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
1c230 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1c240 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  eout].*/.SQLITE_
1c250 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1c260 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
1c270 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
1c280 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c290 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
1c2a0 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
1c2b0 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54  g Queries.** MET
1c2c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1c2d0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67  ** This is a leg
1c2e0 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  acy interface th
1c2f0 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20  at is preserved 
1c300 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1c310 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20  mpatibility..** 
1c320 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  Use of this inte
1c330 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63  rface is not rec
1c340 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
1c350 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
1c360 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
1c370 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
1c380 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
1c390 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
1c3a0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1c3b0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
1c3c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
1c3d0 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
1c3e0 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
1c3f0 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
1c400 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
1c410 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
1c420 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
1c430 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1c440 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
1c450 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
1c460 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
1c470 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1c480 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
1c490 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
1c4a0 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
1c4b0 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
1c4c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1c4d0 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
1c4e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1c4f0 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
1c500 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
1c510 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
1c520 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
1c530 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1c540 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
1c550 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
1c560 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
1c570 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
1c580 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
1c590 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1c5a0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1c5b0 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
1c5c0 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
1c5d0 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
1c5e0 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
1c5f0 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
1c600 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
1c610 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
1c620 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
1c630 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
1c640 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
1c650 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
1c660 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1c670 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
1c680 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
1c690 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1c6a0 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
1c6b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
1c6c0 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
1c6d0 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
1c6e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
1c6f0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
1c700 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
1c710 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
1c720 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1c730 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
1c740 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
1c750 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
1c760 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
1c770 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
1c780 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65   ^(As an example
1c790 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1c7a0 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
1c7b0 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
1c7c0 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
1c7d0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c7e0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c7f0 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
1c800 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
1c810 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
1c820 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
1c830 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
1c840 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
1c850 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
1c860 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
1c870 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
1c880 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1c890 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
1c8a0 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
1c8b0 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
1c8c0 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
1c8d0 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
1c8e0 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
1c8f0 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
1c900 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1c910 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
1c920 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
1c930 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
1c940 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
1c950 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
1c960 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1c970 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
1c980 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
1c990 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
1c9a0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
1c9b0 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
1c9c0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c9d0 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
1c9e0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1c9f0 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
1ca00 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1ca10 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
1ca20 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
1ca30 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
1ca40 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
1ca50 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
1ca60 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
1ca70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1ca80 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
1ca90 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1caa0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1cab0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1cac0 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
1cad0 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
1cae0 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
1caf0 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
1cb00 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
1cb10 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1cb20 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
1cb30 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
1cb40 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
1cb50 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
1cb60 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
1cb70 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
1cb80 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
1cb90 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
1cba0 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
1cbb0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
1cbc0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
1cbd0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1cbe0 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61  ),.** it must pa
1cbf0 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
1cc00 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
1cc10 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1cc20 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
1cc30 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
1cc40 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
1cc50 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
1cc60 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
1cc70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
1cc80 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
1cc90 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
1cca0 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
1ccb0 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
1ccc0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
1ccd0 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
1cce0 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
1ccf0 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
1cd00 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1cd10 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
1cd20 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1cd30 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
1cd40 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
1cd50 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1cd60 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
1cd70 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
1cd80 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
1cd90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1cda0 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
1cdb0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
1cdc0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
1cdd0 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
1cde0 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
1cdf0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
1ce00 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
1ce10 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
1ce20 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
1ce30 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
1ce40 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
1ce50 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
1ce60 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
1ce70 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
1ce80 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
1ce90 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
1cea0 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
1ceb0 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
1cec0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
1ced0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
1cee0 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
1cef0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1cf00 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
1cf10 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74   int sqlite3_get
1cf20 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
1cf30 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1cf40 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
1cf50 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
1cf60 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
1cf70 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
1cf80 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
1cf90 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
1cfa0 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
1cfb0 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
1cfc0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
1cfd0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1cfe0 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
1cff0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
1d000 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
1d010 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1d020 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
1d030 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1d040 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
1d050 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
1d060 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
1d070 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  re */.);.SQLITE_
1d080 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
1d090 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
1d0a0 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
1d0b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
1d0c0 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
1d0d0 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
1d0e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1d0f0 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
1d100 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
1d110 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
1d120 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
1d130 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
1d140 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
1d150 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e  hese routines un
1d160 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66  derstand most of
1d170 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20   the common K&R 
1d180 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1d190 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65  ns,.** plus some
1d1a0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d   additional non-
1d1b0 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73  standard formats
1d1c0 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77  , detailed below
1d1d0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73  ..** Note that s
1d1e0 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20  ome of the more 
1d1f0 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69  obscure formatti
1d200 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20  ng options from 
1d210 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72  recent.** C-libr
1d220 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 72  ary standards ar
1d230 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1d240 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  his implementati
1d250 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
1d260 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1d270 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1d280 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1d290 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1d2a0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1d2b0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1d2c0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1d2d0 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1d2e0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1d2f0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1d300 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1d310 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1d320 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1d330 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1d340 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1d350 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1d360 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1d370 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1d380 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1d390 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1d3a0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1d3b0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1d3c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1d3d0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1d3e0 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1d3f0 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1d400 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1d410 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1d420 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1d430 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1d440 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1d450 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1d460 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1d470 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1d480 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1d490 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1d4a0 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1d4b0 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1d4c0 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1d4d0 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1d4e0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1d4f0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1d500 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1d510 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1d520 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1d530 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1d540 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1d550 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1d560 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1d570 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1d580 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1d590 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1d5a0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1d5b0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1d5c0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1d5d0 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1d5e0 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1d5f0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1d600 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1d610 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1d620 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1d630 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1d640 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1d650 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1d660 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1d670 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1d680 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1d690 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1d6a0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1d6b0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1d6c0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1d6d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1d6e0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1d6f0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1d700 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1d710 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1d720 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1d730 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1d740 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1d750 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1d760 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1d770 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1d780 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1d790 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1d7a0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1d7b0 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1d7c0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1d7d0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1d7e0 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1d7f0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1d800 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1d810 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1d820 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1d830 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1d840 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1d850 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1d860 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1d870 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1d880 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1d890 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1d8a0 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1d8b0 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1d8c0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1d8d0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1d8e0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1d8f0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1d900 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25  %Q", "%w" and "%
1d910 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
1d920 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
1d930 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
1d940 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
1d950 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72  itutes a nul-ter
1d960 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1d970 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
1d980 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
1d990 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
1d9a0 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
1d9b0 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
1d9c0 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
1d9d0 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
1d9e0 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
1d9f0 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
1da00 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
1da10 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
1da20 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
1da30 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
1da40 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
1da50 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
1da60 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
1da70 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
1da80 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
1da90 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
1daa0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1dab0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1dac0 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
1dad0 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
1dae0 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
1daf0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1db00 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
1db10 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
1db20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1db30 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1db40 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1db50 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1db60 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1db70 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1db80 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
1db90 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1dba0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1dbb0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1dbc0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1dbd0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1dbe0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1dbf0 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1dc00 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
1dc10 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
1dc20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
1dc30 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
1dc40 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
1dc50 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
1dc60 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1dc70 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1dc80 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1dc90 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1dca0 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
1dcb0 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
1dcc0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1dcd0 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
1dce0 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
1dcf0 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
1dd00 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
1dd10 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
1dd20 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
1dd30 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
1dd40 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1dd50 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1dd60 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1dd70 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1dd80 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1dd90 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1dda0 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
1ddb0 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
1ddc0 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
1ddd0 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
1dde0 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
1ddf0 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
1de00 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
1de10 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
1de20 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1de30 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
1de40 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
1de50 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
1de60 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
1de70 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
1de80 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
1de90 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
1dea0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
1deb0 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
1dec0 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
1ded0 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
1dee0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
1def0 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
1df00 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
1df10 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
1df20 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
1df30 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
1df40 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
1df50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1df60 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1df70 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1df80 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1df90 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1dfa0 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
1dfb0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1dfc0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1dfd0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1dfe0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1dff0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e000 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
1e010 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
1e020 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
1e030 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1e040 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
1e050 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
1e060 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
1e070 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1e080 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77  .**.** ^(The "%w
1e090 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1e0a0 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22  ion is like "%q"
1e0b0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1e0c0 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65  expects to.** be
1e0d0 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69   contained withi
1e0e0 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20  n double-quotes 
1e0f0 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c  instead of singl
1e100 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74  e quotes, and it
1e110 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 20  .** escapes the 
1e120 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61  double-quote cha
1e130 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f  racter instead o
1e140 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f  f the single-quo
1e150 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e  te.** character.
1e160 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f 72  )^  The "%w" for
1e170 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1e180 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73  s intended for s
1e190 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a  afely inserting.
1e1a0 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  ** table and col
1e1b0 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61  umn names into a
1e1c0 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c   constructed SQL
1e1d0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
1e1e0 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1e1f0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1e200 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1e210 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1e220 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1e230 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1e240 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1e250 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1e260 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1e270 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1e280 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1e290 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1e2a0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1e2b0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1e2c0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1e2d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1e2e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1e2f0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1e300 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49  , va_list);.SQLI
1e310 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1e320 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
1e330 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1e340 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54  ar*, ...);.SQLIT
1e350 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1e360 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1e370 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1e380 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1e390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e3a0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1e3b0 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1e3c0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1e3d0 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1e3e0 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1e3f0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1e400 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1e410 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1e420 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1e430 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1e440 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1e450 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1e460 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1e470 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1e480 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1e490 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1e4a0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1e4b0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1e4c0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1e4d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e4e0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1e4f0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1e500 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1e510 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1e520 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1e530 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1e540 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1e550 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1e560 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1e570 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1e580 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1e590 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1e5a0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1e5b0 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1e5c0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1e5d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e5e0 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1e5f0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1e600 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1e610 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1e620 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
1e630 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1e640 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72  4(N) routine wor
1e650 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20  ks just like.** 
1e660 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1e670 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1e680 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36  is an unsigned 6
1e690 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e  4-bit integer in
1e6a0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69  stead.** of a si
1e6b0 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65  gned 32-bit inte
1e6c0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ger..**.** ^Call
1e6d0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1e6e0 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1e6f0 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1e700 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1e710 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1e720 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e730 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1e740 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1e750 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1e760 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1e770 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1e780 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1e790 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1e7a0 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1e7b0 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1e7c0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1e7d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1e7e0 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1e7f0 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1e800 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1e810 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1e820 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1e830 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1e840 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1e850 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1e860 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1e870 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1e880 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1e890 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1e8a0 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1e8b0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1e8c0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1e8d0 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1e8e0 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1e8f0 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1e900 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1e910 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1e920 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1e930 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1e940 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1e950 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1e960 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e970 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1e980 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1e990 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1e9a0 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1e9b0 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65  location X to be
1e9c0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1e9d0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20  s..** ^If the X 
1e9e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1e9f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1ea00 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1ea10 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1ea20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1ea30 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1ea40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1ea50 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  oc(N)..** ^If th
1ea60 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1ea70 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ea80 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72  (X,N) is zero or
1ea90 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1eaa0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1eab0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1eac0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1ead0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29   sqlite3_free(X)
1eae0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1eaf0 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1eb00 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1eb10 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1eb20 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1eb30 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1eb40 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e  ze or NULL if in
1eb50 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1eb60 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  y is available..
1eb70 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1eb80 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1eb90 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1eba0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1ebb0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1ebc0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1ebd0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1ebe0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1ebf0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1ec00 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1ec10 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65  loc(X,N) and the
1ec20 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1ec30 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1ec40 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1ec50 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1ec60 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f  NULL and N is po
1ec70 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  sitive, then the
1ec80 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  .** prior alloca
1ec90 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65  tion is not free
1eca0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1ecb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1ecc0 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20  X,N) interfaces 
1ecd0 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61  works the same a
1ece0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  s.** sqlite3_rea
1ecf0 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74  lloc(X,N) except
1ed00 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d   that N is a 64-
1ed10 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
1ed20 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1ed30 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
1ed40 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1ed50 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d  * ^If X is a mem
1ed60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70  ory allocation p
1ed70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
1ed80 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1ed90 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  malloc(),.** sql
1eda0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1edb0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1edc0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  (), or sqlite3_r
1edd0 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e  ealloc64(), then
1ede0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1edf0 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(X) returns the
1ee00 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65   size of that me
1ee10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1ee20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68  in bytes..** ^Th
1ee30 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1ee40 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   by sqlite3_msiz
1ee50 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61  e(X) might be la
1ee60 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75  rger than the nu
1ee70 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
1ee80 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20   requested when 
1ee90 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e  X was allocated.
1eea0 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c    ^If X is a NUL
1eeb0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
1eec0 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1eed0 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  X) returns zero.
1eee0 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f    If X points to
1eef0 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20   something that 
1ef00 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65  is not.** the be
1ef10 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72  ginning of memor
1ef20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72  y allocation, or
1ef30 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f   if it points to
1ef40 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76   a formerly.** v
1ef50 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  alid memory allo
1ef60 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20  cation that has 
1ef70 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20  now been freed, 
1ef80 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1ef90 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  r.** of sqlite3_
1efa0 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65  msize(X) is unde
1efb0 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62  fined and possib
1efc0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1efd0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1efe0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1eff0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69  3_malloc(), sqli
1f000 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a  te3_realloc(),.*
1f010 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1f020 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  64(), and sqlite
1f030 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a  3_realloc64().**
1f040 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1f050 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1f060 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1f070 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1f080 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1f090 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1f0a0 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1f0b0 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1f0c0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1f0d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1f0e0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1f0f0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1f100 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1f110 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1f120 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1f130 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1f140 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1f150 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1f160 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1f170 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1f180 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1f190 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1f1a0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1f1b0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1f1c0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1f1d0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1f1e0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1f1f0 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1f200 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1f210 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1f220 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1f230 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1f240 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1f250 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1f260 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1f270 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1f280 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1f290 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1f2a0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1f2b0 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1f2c0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1f2d0 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1f2e0 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1f2f0 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1f300 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1f310 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1f320 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1f330 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1f340 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1f350 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1f360 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1f370 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1f380 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1f390 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1f3a0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1f3b0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1f3c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1f3d0 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1f3e0 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1f3f0 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1f400 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1f410 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1f420 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f430 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1f440 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1f450 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1f460 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1f470 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1f480 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1f490 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1f4a0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1f4b0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1f4c0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1f4d0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1f4e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1f4f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1f500 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  loc()]..*/.SQLIT
1f510 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1f520 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1f530 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1f540 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1f550 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64(sqlite3_uint6
1f560 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
1f570 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1f580 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1f590 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1f5a0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1f5b0 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69  oc64(void*, sqli
1f5c0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c  te3_uint64);.SQL
1f5d0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1f5e0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1f5f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
1f600 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69  ite3_uint64 sqli
1f610 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29  te3_msize(void*)
1f620 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f630 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1f640 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1f650 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1f660 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1f670 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1f680 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1f690 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1f6a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1f6b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1f6c0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1f6d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1f6e0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1f6f0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1f700 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1f710 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1f720 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1f730 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1f740 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1f750 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1f760 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1f770 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1f780 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1f790 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1f7a0 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1f7b0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1f7c0 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1f7d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1f7e0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1f7f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1f800 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1f810 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1f820 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1f830 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1f840 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1f850 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1f860 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1f870 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1f880 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1f890 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1f8a0 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1f8b0 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1f8c0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1f8d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1f8e0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1f8f0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1f900 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1f910 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1f920 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1f930 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1f940 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1f950 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1f960 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1f970 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1f980 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1f990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1f9a0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1f9b0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1f9c0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1f9d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1f9e0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1f9f0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1fa00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1fa10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1fa20 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1fa30 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1fa40 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1fa50 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51  the reset..*/.SQ
1fa60 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
1fa70 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1fa80 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1fa90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
1faa0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1fab0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1fac0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1fad0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1fae0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1faf0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1fb00 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1fb10 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1fb20 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1fb30 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1fb40 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1fb50 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1fb60 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1fb70 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1fb80 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1fb90 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1fba0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1fbb0 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1fbc0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1fbd0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1fbe0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1fbf0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1fc00 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1fc10 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1fc20 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1fc30 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1fc40 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1fc50 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1fc60 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1fc70 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1fc80 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1fc90 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1fca0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1fcb0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1fcc0 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
1fcd0 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
1fce0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1fcf0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
1fd00 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
1fd10 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
1fd20 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
1fd30 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
1fd40 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
1fd50 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
1fd60 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
1fd70 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
1fd80 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
1fd90 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
1fda0 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
1fdb0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1fdc0 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
1fdd0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1fde0 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
1fdf0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
1fe00 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1fe10 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
1fe20 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
1fe30 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
1fe40 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
1fe50 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
1fe60 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
1fe70 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
1fe80 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
1fe90 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
1fea0 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
1feb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1fec0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
1fed0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
1fee0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
1fef0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
1ff00 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
1ff10 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
1ff20 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1ff30 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1ff40 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
1ff50 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
1ff60 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
1ff70 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1ff80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1ff90 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
1ffa0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1ffb0 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
1ffc0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1ffd0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
1ffe0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
1fff0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
20000 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
20010 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
20020 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
20030 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
20040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
20050 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
20060 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
20070 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
20080 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
20090 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
200a0 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
200b0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
200c0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
200d0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
200e0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
200f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20100 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
20110 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
20120 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
20130 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
20140 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
20150 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
20160 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
20170 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
20180 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
20190 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
201a0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
201b0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
201c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
201d0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
201e0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
201f0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
20200 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
20210 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
20220 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
20230 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
20240 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
20250 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
20260 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
20270 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
20280 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
20290 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
202a0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
202b0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
202c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
202d0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
202e0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
202f0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
20300 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
20310 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
20320 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
20330 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
20340 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
20350 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
20360 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
20370 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
20380 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
20390 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
203a0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
203b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
203c0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
203d0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
203e0 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
203f0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
20400 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
20410 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
20420 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
20430 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
20440 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
20450 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
20460 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20470 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
20480 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
20490 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
204a0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
204b0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
204c0 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
204d0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
204e0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
204f0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
20500 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
20510 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
20520 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
20530 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
20540 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
20550 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
20560 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
20570 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
20580 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
20590 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
205a0 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
205b0 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
205c0 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
205d0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
205e0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
205f0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
20600 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
20610 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
20620 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
20630 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
20640 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
20650 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20660 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
20670 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
20680 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
20690 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
206a0 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
206b0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
206c0 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
206d0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
206e0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
206f0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
20700 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
20710 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
20720 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
20730 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
20740 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
20750 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
20760 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
20770 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
20780 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
20790 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
207a0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
207b0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
207c0 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
207d0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
207e0 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
207f0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
20800 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
20810 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
20820 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
20830 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
20840 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
20850 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
20860 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
20870 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
20880 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
20890 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
208a0 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
208b0 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
208c0 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
208d0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
208e0 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
208f0 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
20900 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
20910 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
20920 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
20930 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
20940 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
20950 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
20960 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
20970 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
20980 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
20990 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
209a0 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
209b0 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
209c0 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
209d0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
209e0 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
209f0 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
20a00 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
20a10 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
20a20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
20a30 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
20a40 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
20a50 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
20a60 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
20a70 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
20a80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
20a90 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
20aa0 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
20ab0 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
20ac0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
20ad0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
20ae0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
20af0 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
20b00 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
20b10 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
20b20 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
20b30 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
20b40 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
20b50 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
20b60 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
20b70 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
20b80 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
20b90 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
20ba0 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
20bb0 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
20bc0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
20bd0 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
20be0 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
20bf0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
20c00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20c10 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
20c20 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
20c30 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
20c40 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
20c50 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
20c60 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
20c70 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
20c80 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
20c90 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
20ca0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
20cb0 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
20cc0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
20cd0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
20ce0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
20cf0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
20d00 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
20d10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20d20 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
20d30 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
20d40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
20d50 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
20d60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
20d70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
20d80 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
20d90 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
20da0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20db0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
20dc0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
20dd0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
20de0 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
20df0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20e00 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
20e10 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
20e20 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
20e30 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
20e40 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
20e50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
20e60 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
20e70 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
20e80 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
20e90 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
20ea0 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
20eb0 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
20ec0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
20ed0 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
20ee0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
20ef0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
20f00 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
20f10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20f20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
20f30 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
20f40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
20f50 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
20f60 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
20f70 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
20f80 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
20f90 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
20fa0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
20fb0 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
20fc0 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
20fd0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
20fe0 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
20ff0 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
21000 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21010 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
21020 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
21030 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
21040 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ge..*/.SQLITE_AP
21050 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  I int sqlite3_se
21060 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
21070 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
21080 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
21090 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
210a0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
210b0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
210c0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
210d0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
210e0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
210f0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
21100 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
21110 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
21120 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
21130 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
21140 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
21150 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
21160 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
21170 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
21180 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
21190 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
211a0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
211b0 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
211c0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
211d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
211e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
211f0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
21200 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
21210 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
21220 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
21230 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
21240 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
21250 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69  sed as a [confli
21260 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f  ct resolution mo
21270 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  de].** returned 
21280 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
21290 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
212a0 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
212b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
212c0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
212d0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
212e0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
212f0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
21300 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
21310 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
21320 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
21330 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
21340 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
21350 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
21360 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
21370 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
21380 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
21390 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
213a0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
213b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
213c0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
213d0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
213e0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
213f0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
21400 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
21410 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
21420 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
21430 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
21440 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
21450 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
21460 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
21470 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
21480 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
21490 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
214a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
214b0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
214c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
214d0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
214e0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
214f0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
21500 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
21510 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
21520 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
21530 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
21540 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
21550 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
21560 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
21570 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
21580 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
21590 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
215a0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
215b0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
215c0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
215d0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
215e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
215f0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
21600 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
21610 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
21620 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
21630 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
21640 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
21650 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21660 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
21670 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
21680 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
21690 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
216a0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
216b0 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
216c0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
216d0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
216e0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
216f0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
21700 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
21710 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
21720 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21730 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
21740 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
21750 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
21760 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21770 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
21780 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
21790 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
217a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
217b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
217c0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
217d0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
217e0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
217f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21800 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21810 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
21820 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
21830 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
21840 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21850 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21860 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
21870 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
21880 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21890 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
218a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
218b0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
218c0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
218d0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
218e0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
218f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21900 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
21910 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
21920 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21930 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21940 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21950 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
21960 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
21970 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
21980 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21990 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
219a0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
219b0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
219c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
219d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
219e0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
219f0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
21a00 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21a10 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21a20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21a30 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
21a40 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
21a50 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21a60 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21a70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21a80 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
21a90 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
21aa0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21ab0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21ac0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21ad0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
21ae0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
21af0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
21b00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21b10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21b20 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
21b30 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
21b40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
21b50 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21b60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21b70 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
21b80 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
21b90 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
21ba0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21bb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21bc0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
21bd0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
21be0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
21bf0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21c00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21c10 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
21c20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
21c30 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
21c40 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
21c60 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
21c70 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
21c80 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
21c90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21ca0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
21cb0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
21cc0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
21cd0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21ce0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21cf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
21d00 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
21d10 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
21d20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
21d30 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
21d40 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
21d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21d60 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
21d70 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
21d80 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
21d90 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
21da0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
21db0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
21dc0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21dd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21de0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
21df0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
21e00 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
21e10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21e20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21e30 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
21e40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
21e50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21e60 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
21e70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21e80 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
21e90 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
21ea0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
21eb0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21ec0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21ed0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
21ee0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
21ef0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
21f00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21f10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21f20 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
21f30 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
21f40 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
21f50 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21f60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21f70 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
21f80 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
21f90 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
21fa0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21fb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21fc0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
21fd0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
21fe0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21ff0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22010 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
22020 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
22030 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
22040 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
22050 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22060 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
22070 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
22080 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
22090 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
220a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
220b0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
220c0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
220d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
220e0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
220f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
22100 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
22110 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
22120 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
22130 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
22140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
22150 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
22160 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
22170 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
22180 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55  fine SQLITE_RECU
22190 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  RSIVE           
221a0 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   33   /* NULL   
221b0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
221c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a           */../*.
221d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
221e0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
221f0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ng Functions.** 
22200 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
22210 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
22220 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61  ines are depreca
22230 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71  ted. Use the [sq
22240 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
22250 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
22260 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f  nstead of the ro
22270 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64  utines described
22280 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
22290 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
222a0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
222b0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
222c0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
222d0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
222e0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
222f0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
22300 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
22310 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
22320 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
22330 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
22340 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
22350 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
22360 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
22370 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
22380 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
22390 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
223a0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
223b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
223c0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
223d0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
223e0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
223f0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
22400 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
22410 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
22420 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
22430 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
22440 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
22450 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
22460 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
22470 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
22480 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
22490 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
224a0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
224b0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
224c0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
224d0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
224e0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
224f0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
22500 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
22510 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
22520 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
22530 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
22540 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
22550 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
22560 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
22570 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
22580 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
22590 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
225a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
225b0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
225c0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
225d0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
225e0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
225f0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
22600 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
22610 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
22620 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
22630 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
22640 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
22650 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
22660 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
22670 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
22680 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
22690 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
226a0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
226b0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
226c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
226d0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
226e0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
226f0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
22700 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
22710 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
22720 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
22730 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
22740 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
22750 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
22760 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
22770 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
22780 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
22790 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
227a0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
227b0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
227c0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
227d0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
227e0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
227f0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
22800 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
22810 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
22820 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
22830 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
22840 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a  trace(sqlite3*,.
22850 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29     void(*xTrace)
22860 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
22870 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
22880 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
22890 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a  EPRECATED void *
228a0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
228b0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
228c0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
228d0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
228e0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
228f0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
22900 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61  API3REF: SQL Tra
22910 63 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a  ce Event Codes.*
22920 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
22930 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54  TE_TRACE.**.** T
22940 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69  hese constants i
22950 64 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20  dentify classes 
22960 6f 66 20 65 76 65 6e 74 73 20 74 68 61 74 20 63  of events that c
22970 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a  an be monitored.
22980 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ** using the [sq
22990 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
229a0 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e  ] tracing logic.
229b0 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
229c0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
229d0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
229e0 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62  is an OR-ed comb
229f0 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f  ination of one o
22a00 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65  r more of.** the
22a10 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74   following const
22a20 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73  ants.  ^The firs
22a30 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
22a40 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
22a50 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  .** is one of th
22a60 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73  e following cons
22a70 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  tants..**.** New
22a80 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e   tracing constan
22a90 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ts may be added 
22aa0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
22ab0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61  es..**.** ^A tra
22ac0 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20  ce callback has 
22ad0 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20  four arguments: 
22ae0 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c  xCallback(T,C,P,
22af0 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72  X)..** ^The T ar
22b00 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
22b10 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79 70   the integer typ
22b20 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a  e codes above..*
22b30 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e  * ^The C argumen
22b40 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  t is a copy of t
22b50 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  he context point
22b60 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  er passed in as 
22b70 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72  the.** fourth ar
22b80 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
22b90 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a  e3_trace_v2()]..
22ba0 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61  ** The P and X a
22bb0 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69  rguments are poi
22bc0 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e  nters whose mean
22bd0 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54  ings depend on T
22be0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
22bf0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  [[SQLITE_TRACE_S
22c00 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TMT]] <dt>SQLITE
22c10 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e  _TRACE_STMT</dt>
22c20 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
22c30 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61  TE_TRACE_STMT ca
22c40 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
22c50 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72 65  d when a prepare
22c60 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66  d statement.** f
22c70 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e  irst begins runn
22c80 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79  ing and possibly
22c90 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20   at other times 
22ca0 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78  during the.** ex
22cb0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70  ecution of the p
22cc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22cd0 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74 68  t, such as at th
22ce0 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a  e start of each.
22cf0 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70 72  ** trigger subpr
22d00 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72  ogram. ^The P ar
22d10 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
22d20 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70  ter to the.** [p
22d30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22d40 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d  t]. ^The X argum
22d50 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
22d60 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
22d70 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65  ch.** is the une
22d80 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74  xpanded SQL text
22d90 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
22da0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e   statement or an
22db0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a   SQL comment .**
22dc0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
22dd0 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  the invocation o
22de0 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54  f a trigger.  ^T
22df0 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20  he callback can 
22e00 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73  compute.** the s
22e10 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77 6f  ame text that wo
22e20 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72 65  uld have been re
22e30 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65  turned by the le
22e40 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72  gacy [sqlite3_tr
22e50 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ace()].** interf
22e60 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68 65  ace by using the
22e70 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e   X argument when
22e80 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20 22   X begins with "
22e90 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  --" and invoking
22ea0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70  .** [sqlite3_exp
22eb0 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74  anded_sql(P)] ot
22ec0 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b  herwise..**.** [
22ed0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52  [SQLITE_TRACE_PR
22ee0 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  OFILE]] <dt>SQLI
22ef0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
22f00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
22f10 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
22f20 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70  OFILE callback p
22f30 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d  rovides approxim
22f40 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a  ately the same.*
22f50 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  * information as
22f60 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
22f70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  the [sqlite3_pro
22f80 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b  file()] callback
22f90 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75  ..** ^The P argu
22fa0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
22fb0 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
22fc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
22fd0 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d  d the.** X argum
22fe0 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
22ff0 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77  64-bit integer w
23000 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74 69  hich is the esti
23010 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20  mated of.** the 
23020 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65  number of nanose
23030 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70 72  cond that the pr
23040 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23050 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
23060 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41   ^The SQLITE_TRA
23070 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62  CE_PROFILE callb
23080 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23090 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
230a0 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a  t finishes..**.*
230b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
230c0 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _ROW]] <dt>SQLIT
230d0 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e  E_TRACE_ROW</dt>
230e0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
230f0 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c  TE_TRACE_ROW cal
23100 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
23110 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65 70   whenever a prep
23120 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
23130 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73 69  t generates a si
23140 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75  ngle row of resu
23150 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20  lt.  .** ^The P 
23160 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
23170 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72  inter to the [pr
23180 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23190 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61  ] and the.** X a
231a0 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65  rgument is unuse
231b0 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d..**.** [[SQLIT
231c0 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20  E_TRACE_CLOSE]] 
231d0 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
231e0 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
231f0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
23200 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61  ACE_CLOSE callba
23210 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
23220 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  en a database.**
23230 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
23240 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  es..** ^The P ar
23250 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
23260 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
23270 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23280 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74   object.** and t
23290 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  he X argument is
232a0 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c   unused..** </dl
232b0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
232c0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20  ITE_TRACE_STMT  
232d0 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e       0x01.#defin
232e0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  e SQLITE_TRACE_P
232f0 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23  ROFILE    0x02.#
23300 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
23310 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30  ACE_ROW        0
23320 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x04.#define SQLI
23330 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20  TE_TRACE_CLOSE  
23340 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20      0x08../*.** 
23350 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72  CAPI3REF: SQL Tr
23360 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48  ace Hook.** METH
23370 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
23380 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
23390 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29  race_v2(D,M,X,P)
233a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
233b0 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61 6c  ters a trace cal
233c0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
233d0 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74  n X against [dat
233e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
233f0 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65  ] D, using prope
23400 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e  rty mask M.** an
23410 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  d context pointe
23420 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20  r P.  ^If the X 
23430 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e  callback is.** N
23440 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20  ULL or if the M 
23450 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68  mask is zero, th
23460 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64 69  en tracing is di
23470 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  sabled.  The.** 
23480 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  M argument shoul
23490 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73 65  d be the bitwise
234a0 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
234b0 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72  on of.** zero or
234c0 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52   more [SQLITE_TR
234d0 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  ACE] constants..
234e0 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c  **.** ^Each call
234f0 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74   to either sqlit
23500 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71  e3_trace() or sq
23510 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
23520 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28   overrides .** (
23530 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69  cancels) any pri
23540 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  or calls to sqli
23550 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73  te3_trace() or s
23560 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23570 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20  )..**.** ^The X 
23580 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
23590 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79  ked whenever any
235a0 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20 69   of the events i
235b0 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a  dentified by .**
235c0 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20   mask M occur.  
235d0 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65 74  ^The integer ret
235e0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74  urn value from t
235f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63  he callback is c
23600 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f  urrently.** igno
23610 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73  red, though this
23620 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66   may change in f
23630 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20  uture releases. 
23640 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70   Callback.** imp
23650 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
23660 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20  uld return zero 
23670 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72 65  to ensure future
23680 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
23690 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63  **.** ^A trace c
236a0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
236b0 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72 67  ed with four arg
236c0 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b  uments: callback
236d0 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54  (T,C,P,X)..** ^T
236e0 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73  he T argument is
236f0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c   one of the [SQL
23700 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f  ITE_TRACE].** co
23710 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63  nstants to indic
23720 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c  ate why the call
23730 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64  back was invoked
23740 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75  ..** ^The C argu
23750 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f  ment is a copy o
23760 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f  f the context po
23770 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20  inter..** The P 
23780 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20  and X arguments 
23790 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f  are pointers who
237a0 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65  se meanings depe
237b0 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54  nd on T..**.** T
237c0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
237d0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
237e0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72  is intended to r
237f0 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63  eplace the legac
23800 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
23810 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
23820 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
23830 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20  rofile()], both 
23840 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20  of which.** are 
23850 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 53  deprecated..*/.S
23860 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
23870 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a  lite3_trace_v2(.
23880 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e    sqlite3*,.  un
23890 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20  signed uMask,.  
238a0 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28  int(*xCallback)(
238b0 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76  unsigned,void*,v
238c0 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76  oid*,void*),.  v
238d0 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a  oid *pCtx.);../*
238e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
238f0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
23900 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
23910 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23920 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
23930 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
23940 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
23950 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
23960 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
23970 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
23980 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
23990 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
239a0 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
239b0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
239c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
239d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
239e0 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
239f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
23a00 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
23a10 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
23a20 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
23a30 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
23a40 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
23a50 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
23a60 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
23a70 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
23a80 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
23a90 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
23aa0 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
23ab0 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
23ac0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
23ad0 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
23ae0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
23af0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
23b00 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
23b10 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
23b20 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
23b30 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
23b40 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
23b50 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
23b60 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
23b70 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
23b80 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
23b90 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
23ba0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
23bb0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
23bc0 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
23bd0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
23be0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23bf0 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
23c00 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
23c10 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
23c20 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
23c30 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
23c40 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
23c50 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
23c60 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
23c70 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
23c80 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
23c90 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
23ca0 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
23cb0 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
23cc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
23cd0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
23ce0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
23cf0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
23d00 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
23d10 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
23d20 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
23d30 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
23d40 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
23d50 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
23d60 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
23d70 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
23d80 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
23d90 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
23da0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
23db0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
23dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
23dd0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
23de0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23df0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
23e00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23e10 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
23e20 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
23e30 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
23e40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23e50 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
23e60 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
23e70 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
23e80 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54  aph..**.*/.SQLIT
23e90 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
23ea0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
23eb0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
23ec0 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
23ed0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
23ee0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
23ef0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
23f00 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
23f10 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
23f20 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
23f30 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
23f40 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
23f50 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
23f60 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
23f70 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
23f80 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
23f90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
23fa0 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
23fb0 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
23fc0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
23fd0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
23fe0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
23ff0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
24000 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
24010 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
24020 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
24030 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
24040 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
24050 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
24060 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
24070 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
24080 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
24090 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
240a0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
240b0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
240c0 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
240d0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
240e0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
240f0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
24100 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
24110 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
24120 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
24130 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
24140 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24150 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
24160 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
24170 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
24180 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
24190 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
241a0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
241b0 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
241c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
241d0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
241e0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
241f0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
24200 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
24210 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
24220 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
24230 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
24240 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
24250 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
24260 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
24270 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
24280 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
24290 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
242a0 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
242b0 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
242c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
242d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
242e0 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
242f0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
24300 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
24310 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
24320 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
24330 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
24340 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
24350 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
24360 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
24370 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
24380 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
24390 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
243a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
243b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
243c0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
243d0 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
243e0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
243f0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
24400 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
24410 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
24420 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
24430 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24440 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
24450 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
24460 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
24470 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
24480 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
24490 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
244a0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
244b0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
244c0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
244d0 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
244e0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
244f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24500 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
24510 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
24520 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
24530 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
24540 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
24550 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
24560 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
24570 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
24580 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
24590 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
245a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
245b0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
245c0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
245d0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
245e0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
245f0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
24600 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
24610 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
24620 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
24630 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
24640 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
24650 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
24660 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
24670 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
24680 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
24690 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
246a0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
246b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
246c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
246d0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
246e0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
246f0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
24700 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
24710 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
24720 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
24730 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
24740 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
24750 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
24760 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
24770 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
24780 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
24790 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
247a0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
247b0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
247c0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
247d0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
247e0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
247f0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
24800 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
24810 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
24820 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
24830 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
24840 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
24850 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
24860 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
24870 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
24880 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
24890 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
248a0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
248b0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
248c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
248d0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
248e0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
248f0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
24900 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
24910 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
24920 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
24930 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
24940 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
24950 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
24960 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
24970 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
24980 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
24990 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
249a0 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
249b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
249c0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
249d0 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
249e0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
249f0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
24a00 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
24a10 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
24a20 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
24a30 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
24a40 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
24a50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
24a60 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
24a70 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
24a80 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24a90 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
24aa0 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
24ab0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
24ac0 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
24ad0 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
24ae0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
24af0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
24b00 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
24b10 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
24b20 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
24b30 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
24b40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
24b50 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
24b60 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
24b70 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
24b80 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
24b90 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
24ba0 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
24bb0 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
24bc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
24bd0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
24be0 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
24bf0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
24c00 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
24c10 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
24c20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
24c30 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
24c40 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
24c50 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
24c60 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
24c70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
24c80 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
24c90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24ca0 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
24cb0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
24cc0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
24cd0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
24ce0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
24cf0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
24d00 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
24d10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
24d20 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
24d30 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
24d40 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
24d50 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
24d60 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
24d70 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
24d80 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
24d90 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
24da0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
24db0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
24dc0 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
24dd0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
24de0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
24df0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
24e00 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
24e10 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
24e20 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
24e30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24e40 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
24e50 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
24e60 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
24e70 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
24e80 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
24e90 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
24ea0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
24eb0 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
24ec0 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
24ed0 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
24ee0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24ef0 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
24f00 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
24f10 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
24f20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
24f30 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
24f40 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
24f50 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
24f60 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
24f70 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
24f80 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
24f90 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
24fa0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
24fb0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
24fc0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
24fd0 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
24fe0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
24ff0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
25000 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
25010 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
25020 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25030 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
25040 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
25050 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
25060 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
25070 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
25080 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
25090 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
250a0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
250b0 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
250c0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
250d0 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
250e0 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
250f0 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
25100 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
25110 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
25120 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
25130 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
25140 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
25150 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
25160 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
25170 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
25180 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25190 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
251a0 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
251b0 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
251c0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
251d0 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
251e0 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
251f0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
25200 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
25210 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
25220 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
25230 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
25240 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
25250 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
25260 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
25270 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
25280 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
25290 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
252a0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
252b0 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
252c0 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
252d0 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
252e0 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
252f0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
25300 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
25310 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
25320 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
25330 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
25340 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
25350 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
25360 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
25370 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
25380 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
25390 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
253a0 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
253b0 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
253c0 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
253d0 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
253e0 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
253f0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
25400 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
25410 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
25420 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
25430 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
25440 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
25450 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
25460 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
25470 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
25480 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
25490 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
254a0 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
254b0 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
254c0 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
254d0 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
254e0 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
254f0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
25500 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
25510 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
25520 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
25530 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
25540 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
25550 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
25560 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
25570 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
25580 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
25590 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
255a0 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
255b0 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
255c0 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68  ^(On windows, th
255d0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
255e0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
255f0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
25600 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
25610 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29  on (e.g. "C:").)
25620 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ^.**.** [[core U
25630 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
25640 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
25650 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
25660 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
25670 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
25680 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
25690 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
256a0 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
256b0 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
256c0 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
256d0 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
256e0 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74  te and its built
256f0 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65  -in [VFSes] inte
25700 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c  rpret the.** fol
25710 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72  lowing query par
25720 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
25730 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
25740 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
25750 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
25760 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
25770 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
25780 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
25790 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
257a0 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
257b0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
257c0 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
257d0 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
257e0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
257f0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
25800 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
25810 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
25820 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
25830 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
25840 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
25850 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
25860 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
25870 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
25880 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
25890 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
258a0 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
258b0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
258c0 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
258d0 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
258e0 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
258f0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
25900 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
25910 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
25920 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
25930 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
25940 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
25950 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
25960 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
25970 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
25980 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
25990 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
259a0 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
259b0 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
259c0 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
259d0 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
259e0 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
259f0 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
25a00 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
25a10 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
25a20 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
25a30 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
25a40 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
25a50 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
25a60 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
25a70 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
25a80 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
25a90 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
25aa0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25ab0 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
25ac0 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
25ad0 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
25ae0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
25af0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
25b00 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
25b10 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
25b20 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
25b30 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
25b40 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
25b50 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
25b60 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
25b70 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
25b80 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
25b90 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
25ba0 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
25bb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25bc0 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
25bd0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
25be0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
25bf0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
25c00 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
25c10 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
25c20 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
25c30 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
25c40 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
25c50 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
25c60 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
25c70 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
25c80 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
25c90 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
25ca0 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
25cb0 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
25cc0 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
25cd0 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
25ce0 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
25cf0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
25d00 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
25d10 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
25d20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
25d30 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
25d40 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
25d50 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
25d60 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
25d70 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
25d80 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
25d90 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
25da0 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
25db0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
25dc0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
25dd0 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
25de0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
25df0 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
25e00 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
25e10 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
25e20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
25e30 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
25e40 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
25e50 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
25e60 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
25e70 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
25e80 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
25e90 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
25ea0 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
25eb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
25ec0 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
25ed0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
25ee0 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
25ef0 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
25f00 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
25f10 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
25f20 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
25f30 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
25f40 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
25f50 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  flag..**.**  <li
25f60 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e  > <b>psow</b>: ^
25f70 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74  The psow paramet
25f80 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65  er indicates whe
25f90 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a  ther or not the.
25fa0 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66  **     [powersaf
25fb0 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f  e overwrite] pro
25fc0 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f  perty does or do
25fd0 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20  es not apply to 
25fe0 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61  the.**     stora
25ff0 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63  ge media on whic
26000 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  h the database f
26010 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a  ile resides..**.
26020 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
26030 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
26040 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
26050 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
26060 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
26070 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
26080 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
26090 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
260a0 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
260b0 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
260c0 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
260d0 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
260e0 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
260f0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
26100 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
26110 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
26120 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
26130 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
26140 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
26150 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
26160 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
26170 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
26180 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
26190 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
261a0 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
261b0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
261c0 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
261d0 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
261e0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
261f0 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
26200 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
26210 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
26220 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26230 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
26240 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
26250 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
26260 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
26270 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
26280 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
26290 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
262a0 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
262b0 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
262c0 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
262d0 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
262e0 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
262f0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
26300 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
26310 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
26320 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
26330 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
26340 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
26350 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
26360 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
26370 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
26380 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
26390 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
263a0 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
263b0 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
263c0 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
263d0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
263e0 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
263f0 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
26400 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
26410 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
26420 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
26430 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
26440 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
26450 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
26460 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
26470 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
26480 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
26490 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
264a0 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
264b0 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
264c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
264d0 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
264e0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
264f0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
26500 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
26510 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
26520 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
26530 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
26540 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
26550 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
26560 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
26570 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
26580 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
26590 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
265a0 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
265b0 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
265c0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
265d0 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
265e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
265f0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
26600 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
26610 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
26620 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26630 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26640 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
26650 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
26660 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
26670 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
26680 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
26690 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
266a0 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
266b0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
266c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
266d0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
266e0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
266f0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
26700 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
26710 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
26720 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
26730 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
26740 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
26750 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
26760 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
26770 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
26780 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
26790 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
267a0 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
267b0 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
267c0 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
267d0 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
267e0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
267f0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
26800 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
26810 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
26820 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
26830 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
26840 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
26850 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
26860 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
26870 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
26880 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
26890 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
268a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
268b0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
268c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
268d0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
268e0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
268f0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26900 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
26910 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
26920 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
26930 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
26940 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
26950 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
26960 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
26970 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
26980 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
26990 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
269a0 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
269b0 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
269c0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
269d0 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
269e0 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
269f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
26a00 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
26a10 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
26a20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
26a30 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
26a40 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
26a50 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
26a60 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
26a70 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
26a80 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
26a90 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
26aa0 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
26ab0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
26ac0 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
26ad0 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
26ae0 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
26af0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
26b00 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
26b10 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
26b20 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
26b30 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
26b40 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
26b50 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
26b60 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
26b70 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
26b80 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
26b90 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
26ba0 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
26bb0 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
26bc0 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
26bd0 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
26be0 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
26bf0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
26c00 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
26c10 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
26c20 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
26c30 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
26c40 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
26c50 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
26c60 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
26c70 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
26c80 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
26c90 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
26ca0 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
26cb0 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
26cc0 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
26cd0 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
26ce0 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
26cf0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
26d00 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
26d10 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
26d20 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
26d30 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
26d40 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
26d50 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
26d60 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
26d70 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
26d80 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
26d90 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
26da0 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
26db0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
26dc0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
26dd0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
26de0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
26df0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
26e00 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
26e10 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
26e20 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
26e30 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
26e40 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
26e50 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
26e60 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
26e70 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
26e80 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
26e90 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
26ea0 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
26eb0 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
26ec0 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
26ed0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
26ee0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
26ef0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26f00 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
26f10 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
26f20 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
26f30 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
26f40 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
26f50 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
26f60 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
26f70 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
26f80 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26f90 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
26fa0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
26fb0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
26fc0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
26fd0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
26fe0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
26ff0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
27000 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
27010 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27020 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
27030 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
27040 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
27050 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
27060 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
27070 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
27080 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
27090 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
270a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
270b0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
270c0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
270d0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
270e0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
270f0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
27100 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
27110 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
27120 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
27130 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
27140 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
27150 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
27160 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
27170 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
27180 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
27190 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
271a0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
271b0 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
271c0 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
271d0 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
271e0 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
271f0 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
27200 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
27210 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
27220 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
27230 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
27240 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
27250 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
27260 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
27270 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
27280 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
27290 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
272a0 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
272b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
272c0 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
272d0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
272e0 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
272f0 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
27300 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
27310 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
27320 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
27330 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
27340 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
27350 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
27360 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
27370 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
27380 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
27390 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
273a0 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
273b0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
273c0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
273d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
273e0 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
273f0 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
27400 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
27410 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
27420 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
27430 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
27440 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
27450 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
27460 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
27470 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
27480 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
27490 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
274a0 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
274b0 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
274c0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
274d0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
274e0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
274f0 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
27500 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
27510 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
27520 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
27530 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
27540 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
27550 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
27560 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
27570 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27580 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
27590 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
275a0 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
275b0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
275c0 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
275d0 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
275e0 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
275f0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
27600 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
27610 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
27620 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
27630 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27640 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
27650 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
27660 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
27670 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
27680 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
27690 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
276a0 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
276b0 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
276c0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
276d0 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
276e0 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
276f0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
27700 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
27710 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
27720 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
27730 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
27740 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
27750 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27760 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
27770 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27780 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
27790 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
277a0 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
277b0 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
277c0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
277d0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
277e0 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
277f0 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
27800 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
27810 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
27820 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
27830 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
27840 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
27850 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
27860 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
27870 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
27880 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
27890 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
278a0 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
278b0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
278c0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
278d0 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
278e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
278f0 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
27900 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
27910 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
27920 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
27930 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
27940 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
27950 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
27960 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
27970 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
27980 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
27990 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53  ndesirable..*/.S
279a0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
279b0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
279c0 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
279d0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
279e0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
279f0 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41  Param);.SQLITE_A
27a00 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  PI int sqlite3_u
27a10 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
27a20 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
27a30 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
27a40 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
27a50 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
27a60 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
27a70 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
27a80 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
27a90 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
27aa0 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
27ab0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
27ac0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
27ad0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
27ae0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te3.**.** ^If th
27af0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71  e most recent sq
27b00 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
27b10 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
27b20 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63   .** [database c
27b30 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69  onnection] D fai
27b40 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71  led, then the sq
27b50 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29  lite3_errcode(D)
27b60 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
27b70 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
27b80 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
27b90 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  or [extended res
27ba0 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
27bb0 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a  at.** API call..
27bc0 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  ** If the most r
27bd0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77  ecent API call w
27be0 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a  as successful,.*
27bf0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
27c00 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
27c10 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
27c20 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
27c30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
27c40 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
27c50 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
27c60 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
27c70 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
27c80 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
27c90 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
27ca0 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
27cb0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
27cc0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
27cd0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
27ce0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
27cf0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
27d00 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
27d10 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
27d20 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
27d30 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
27d40 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
27d50 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
27d60 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
27d70 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
27d80 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27d90 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
27da0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
27db0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
27dc0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
27dd0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
27de0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
27df0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
27e00 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
27e10 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
27e20 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
27e30 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
27e40 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
27e50 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
27e60 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
27e70 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
27e80 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
27e90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27ea0 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
27eb0 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
27ec0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
27ed0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
27ee0 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
27ef0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
27f00 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
27f10 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
27f20 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
27f30 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
27f40 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
27f50 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
27f60 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
27f70 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
27f80 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
27f90 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
27fa0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
27fb0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
27fc0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
27fd0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
27fe0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
27ff0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
28000 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
28010 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
28020 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
28030 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
28040 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
28050 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
28060 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
28070 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
28080 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
28090 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
280a0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
280b0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
280c0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
280d0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
280e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
280f0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
28100 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
28110 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
28120 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
28130 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
28140 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
28150 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
28160 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
28170 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
28180 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
28190 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
281a0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
281b0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
281c0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
281d0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
281e0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
281f0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
28200 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
28210 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
28220 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
28230 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
28240 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
28250 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
28260 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
28270 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
28280 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
28290 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  I int sqlite3_er
282a0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
282b0 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  b);.SQLITE_API i
282c0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
282d0 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
282e0 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
282f0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
28300 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
28310 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
28320 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
28330 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
28340 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  16(sqlite3*);.SQ
28350 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
28360 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
28370 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
28380 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61   CAPI3REF: Prepa
28390 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
283a0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
283b0 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
283c0 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
283d0 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
283e0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
283f0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
28400 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
28410 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
28420 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e  that.** has been
28430 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62   compiled into b
28440 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69  inary form and i
28450 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76  s ready to be ev
28460 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  aluated..**.** T
28470 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c  hink of each SQL
28480 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20   statement as a 
28490 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65  separate compute
284a0 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a  r program.  The.
284b0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
284c0 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63  text is source c
284d0 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64  ode.  A prepared
284e0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
284f0 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d  t .** is the com
28500 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64  piled object cod
28510 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74  e.  All SQL must
28520 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   be converted in
28530 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64  to a.** prepared
28540 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72   statement befor
28550 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e  e it can be run.
28560 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d  .**.** The life-
28570 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61  cycle of a prepa
28580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
28590 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65  ject usually goe
285a0 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  s like this:.**.
285b0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
285c0 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61  Create the prepa
285d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
285e0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
285f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28600 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  ]..** <li> Bind 
28610 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d  values to [param
28620 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
28630 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
28640 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
28650 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
28660 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
28670 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
28680 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
28690 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
286a0 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61   Reset the prepa
286b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
286c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
286d0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
286e0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
286f0 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
28700 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
28710 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
28720 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
28730 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
28740 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
28750 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  l>.*/.typedef st
28760 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
28770 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
28780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28790 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
287a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
287b0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  te3.**.** ^(This
287c0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
287d0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
287e0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
287f0 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
28800 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
28810 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
28820 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
28830 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
28840 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
28850 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
28860 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
28870 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
28880 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
28890 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
288a0 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
288b0 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
288c0 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
288d0 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
288e0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
288f0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
28900 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
28910 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
28920 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
28930 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
28940 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
28950 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
28960 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
28970 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f  changed..** ^(Fo
28980 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74  r each limit cat
28990 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d  egory SQLITE_LIM
289a0 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74  IT_<i>NAME</i> t
289b0 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
289c0 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
289d0 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
289e0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
289f0 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65   by a C preproce
28a00 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65  ssor macro calle
28a10 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53  d.** [limits | S
28a20 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d  QLITE_MAX_<i>NAM
28a30 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20  E</i>]..** (The 
28a40 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
28a50 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
28a60 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
28a70 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
28a80 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
28a90 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
28aa0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
28ab0 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
28ac0 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
28ad0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
28ae0 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73  *.** ^Regardless
28af0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
28b00 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73  ot the limit was
28b10 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a   changed, the .*
28b20 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  * [sqlite3_limit
28b30 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
28b40 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20  turns the prior 
28b50 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
28b60 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74  it..** ^Hence, t
28b70 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65  o find the curre
28b80 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69  nt value of a li
28b90 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e  mit without chan
28ba0 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70  ging it,.** simp
28bb0 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69  ly invoke this i
28bc0 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68  nterface with th
28bd0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
28be0 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a  r set to -1..**.
28bf0 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
28c00 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
28c10 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
28c20 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
28c30 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
28c40 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
28c50 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
28c60 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
28c70 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
28c80 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
28c90 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
28ca0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
28cb0 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
28cc0 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
28cd0 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
28ce0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
28cf0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
28d00 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
28d10 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
28d20 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
28d30 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
28d40 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
28d50 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
28d60 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
28d70 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
28d80 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
28d90 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
28da0 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
28db0 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
28dc0 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
28dd0 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
28de0 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
28df0 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
28e00 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
28e10 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
28e20 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
28e30 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
28e40 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
28e50 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
28e60 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
28e70 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
28e80 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
28e90 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
28ea0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
28eb0 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
28ec0 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
28ed0 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
28ee0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
28ef0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
28f00 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
28f10 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
28f20 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
28f30 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
28f40 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
28f50 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
28f60 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
28f70 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
28f80 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
28f90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
28fa0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
28fb0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
28fc0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
28fd0 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
28fe0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
28ff0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
29000 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
29010 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
29020 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
29030 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
29040 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
29050 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
29060 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
29070 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
29080 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
29090 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
290a0 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
290b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
290c0 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
290d0 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
290e0 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
290f0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
29100 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
29110 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29120 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
29130 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29140 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
29150 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
29160 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
29170 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
29180 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29190 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
291a0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
291b0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
291c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
291d0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
291e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
291f0 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
29200 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29210 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
29220 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29230 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
29240 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29250 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
29260 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
29270 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
29280 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
29290 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
292a0 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
292b0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
292c0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
292d0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
292e0 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
292f0 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
29300 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29310 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
29320 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29330 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
29340 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29350 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
29360 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
29370 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
29380 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29390 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
293a0 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
293b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
293c0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
293d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
293e0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
293f0 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
29400 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
29410 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
29420 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29430 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
29440 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29450 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
29460 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29470 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
29480 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
29490 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
294a0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
294b0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
294c0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
294d0 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
294e0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
294f0 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
29500 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
29510 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
29520 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
29530 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
29540 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29550 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
29560 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29570 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
29580 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29590 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
295a0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
295b0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
295c0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
295d0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
295e0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
295f0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
29600 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29610 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29620 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
29630 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
29640 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
29650 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
29660 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
29670 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
29680 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
29690 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
296a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
296b0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
296c0 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
296d0 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
296e0 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
296f0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
29700 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29710 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
29720 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
29730 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29740 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
29750 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29760 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
29770 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
29780 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
29790 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
297a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
297b0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
297c0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
297d0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
297e0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
297f0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
29800 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
29810 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
29820 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29830 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
29840 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
29850 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
29860 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
29870 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29880 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
29890 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
298a0 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
298b0 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
298c0 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
298d0 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
298e0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
298f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
29900 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
29910 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
29920 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
29930 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
29940 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
29950 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29960 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
29970 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
29980 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29990 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
299a0 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
299b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
299c0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
299d0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
299e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
299f0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
29a00 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
29a10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29a20 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
29a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
29a40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29a50 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
29a60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
29a70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29a80 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
29a90 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
29aa0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
29ab0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
29ac0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
29ad0 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
29ae0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
29af0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
29b00 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
29b10 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
29b20 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
29b30 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
29b40 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
29b50 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
29b60 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
29b70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
29b80 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
29b90 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
29ba0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
29bb0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
29bc0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
29bd0 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
29be0 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
29bf0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
29c00 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
29c10 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
29c20 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
29c30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
29c40 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
29c50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29c60 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
29c70 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
29c80 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
29c90 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
29ca0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
29cb0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
29cc0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
29cd0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
29ce0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
29cf0 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
29d00 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
29d10 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
29d20 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
29d30 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
29d40 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
29d50 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
29d60 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
29d70 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
29d80 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
29d90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
29da0 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
29db0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
29dc0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
29dd0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
29de0 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
29df0 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
29e00 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
29e10 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
29e20 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
29e30 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
29e40 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
29e50 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
29e60 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
29e70 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
29e80 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
29e90 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
29ea0 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
29eb0 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
29ec0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
29ed0 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
29ee0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
29ef0 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
29f00 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
29f10 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
29f20 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
29f30 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
29f40 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
29f50 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
29f60 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
29f70 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
29f80 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
29f90 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
29fa0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
29fb0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
29fc0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
29fd0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
29fe0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
29ff0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
2a000 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
2a010 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
2a020 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
2a030 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
2a040 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
2a050 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2a060 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
2a070 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
2a080 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
2a090 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
2a0a0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
2a0b0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
2a0c0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
2a0d0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
2a0e0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
2a0f0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
2a100 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
2a110 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
2a120 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2a130 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
2a140 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
2a150 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
2a160 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
2a170 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
2a180 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
2a190 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
2a1a0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
2a1b0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
2a1c0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
2a1d0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
2a1e0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
2a1f0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
2a200 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
2a210 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
2a220 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
2a230 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2a240 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
2a250 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
2a260 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
2a270 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
2a280 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
2a290 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
2a2a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
2a2b0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
2a2c0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2a2d0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
2a2e0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
2a2f0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
2a300 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2a310 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
2a320 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2a330 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
2a340 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
2a350 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
2a360 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
2a370 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
2a380 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
2a390 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
2a3a0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
2a3b0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
2a3c0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
2a3d0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
2a3e0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
2a3f0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2a400 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
2a410 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
2a420 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
2a430 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
2a440 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2a450 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
2a460 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
2a470 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
2a480 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
2a490 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
2a4a0 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
2a4b0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
2a4c0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2a4d0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2a4e0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
2a4f0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
2a500 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
2a510 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
2a520 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
2a530 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2a540 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
2a550 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
2a560 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
2a570 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
2a580 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
2a590 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
2a5a0 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
2a5b0 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
2a5c0 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
2a5d0 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
2a5e0 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
2a5f0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
2a600 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
2a610 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
2a620 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
2a630 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
2a640 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
2a650 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
2a660 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
2a670 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2a680 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
2a690 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
2a6a0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
2a6b0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
2a6c0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
2a6d0 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
2a6e0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
2a6f0 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
2a700 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
2a710 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
2a720 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
2a730 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
2a740 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
2a750 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
2a760 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
2a770 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
2a780 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
2a790 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
2a7a0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
2a7b0 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
2a7c0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
2a7d0 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
2a7e0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
2a7f0 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
2a800 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
2a810 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
2a820 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2a830 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
2a840 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
2a850 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
2a860 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
2a870 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
2a880 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
2a890 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
2a8a0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
2a8b0 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
2a8c0 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
2a8d0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
2a8e0 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
2a8f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
2a900 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
2a910 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
2a920 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2a930 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
2a940 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
2a950 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
2a960 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
2a970 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
2a980 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
2a990 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
2a9a0 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
2a9b0 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
2a9c0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
2a9d0 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
2a9e0 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
2a9f0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
2aa00 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
2aa10 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
2aa20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
2aa30 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
2aa40 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
2aa50 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
2aa60 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
2aa70 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
2aa80 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54  * </ol>.*/.SQLIT
2aa90 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2aaa0 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
2aab0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2aac0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2aad0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2aae0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2aaf0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2ab00 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2ab10 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2ab20 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2ab30 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2ab40 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2ab50 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2ab60 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2ab70 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2ab80 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2ab90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2aba0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2abb0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2abc0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2abd0 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
2abe0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2abf0 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
2ac00 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2ac10 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2ac20 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2ac30 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2ac40 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2ac50 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2ac60 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2ac70 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2ac80 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2ac90 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2aca0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2acb0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2acc0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2acd0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2ace0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2acf0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2ad00 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2ad10 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2ad20 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
2ad30 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2ad40 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
2ad50 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2ad60 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2ad70 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2ad80 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2ad90 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2ada0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2adb0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2adc0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2add0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2ade0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2adf0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2ae00 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2ae10 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2ae20 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2ae30 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2ae40 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2ae50 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2ae60 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2ae70 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
2ae80 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ae90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
2aea0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2aeb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2aec0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2aed0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2aee0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2aef0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2af00 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2af10 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2af20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2af30 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2af40 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2af50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2af60 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2af70 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2af80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2af90 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2afa0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2afb0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2afc0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
2afd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2afe0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
2aff0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48  ment SQL.** METH
2b000 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2b010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b020 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  te3_sql(P) inter
2b030 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2b040 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79  ointer to a copy
2b050 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a   of the UTF-8.**
2b060 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
2b070 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72  o create [prepar
2b080 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20  ed statement] P 
2b090 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61  if P was.** crea
2b0a0 74 65 64 20 62 79 20 65 69 74 68 65 72 20 5b 73  ted by either [s
2b0b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b0c0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2b0d0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2b0e0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2b0f0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
2b100 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b110 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2b120 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69   a UTF-8.** stri
2b130 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
2b140 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72  e SQL text of pr
2b150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b160 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e   P with.** [boun
2b170 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78  d parameters] ex
2b180 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  panded..**.** ^(
2b190 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
2b1a0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2b1b0 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20  ment is created 
2b1c0 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a  using the SQL.**
2b1d0 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61   text "SELECT $a
2b1e0 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20  bc,:xyz" and if 
2b1f0 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69  parameter $abc i
2b200 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67  s bound to integ
2b210 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70  er 2345.** and p
2b220 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73  arameter :xyz is
2b230 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73   unbound, then s
2b240 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c  qlite3_sql() wil
2b250 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  l return.** the 
2b260 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c  original string,
2b270 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78   "SELECT $abc,:x
2b280 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f  yz" but sqlite3_
2b290 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a  expanded_sql().*
2b2a0 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53  * will return "S
2b2b0 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22  ELECT 2345,NULL"
2b2c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
2b2d0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2b2e0 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  sql() interface 
2b2f0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
2b300 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
2b310 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61  ory.** is availa
2b320 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ble to hold the 
2b330 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68  result, or if th
2b340 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65  e result would e
2b350 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65  xceed the.** the
2b360 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20   maximum string 
2b370 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65  length determine
2b380 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  d by the [SQLITE
2b390 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a  _LIMIT_LENGTH]..
2b3a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
2b3b0 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
2b3c0 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
2b3d0 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20  e option limits 
2b3e0 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62  the size of.** b
2b3f0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65  ound parameter e
2b400 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65  xpansions.  ^The
2b410 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52   [SQLITE_OMIT_TR
2b420 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
2b430 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73  e.** option caus
2b440 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  es sqlite3_expan
2b450 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77  ded_sql() to alw
2b460 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  ays return NULL.
2b470 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69  .**.** ^The stri
2b480 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ng returned by s
2b490 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73  qlite3_sql(P) is
2b4a0 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69   managed by SQLi
2b4b0 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74  te and is.** aut
2b4c0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64  omatically freed
2b4d0 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72   when the prepar
2b4e0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2b4f0 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54  finalized..** ^T
2b500 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2b510 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78  ed by sqlite3_ex
2b520 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f  panded_sql(P), o
2b530 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64  n the other hand
2b540 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64  ,.** is obtained
2b550 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2b560 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73  alloc()] and mus
2b570 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65  t be free by the
2b580 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
2b590 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  by passing it to
2b5a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2b5b0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2b5c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2b5d0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
2b5e0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 53  _stmt *pStmt);.S
2b5f0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
2b600 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2b610 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2b620 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2b630 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
2b640 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
2b650 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
2b660 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
2b670 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b680 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2b690 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2b6a0 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
2b6b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2b6c0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
2b6d0 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
2b6e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b6f0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
2b700 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
2b710 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
2b720 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2b730 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
2b740 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
2b750 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2b760 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
2b770 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
2b780 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
2b790 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
2b7a0 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
2b7b0 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
2b7c0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
2b7d0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
2b7e0 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
2b7f0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
2b800 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
2b810 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
2b820 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
2b830 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
2b840 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
2b850 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2b860 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
2b870 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
2b880 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
2b890 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
2b8a0 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
2b8b0 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
2b8c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
2b8d0 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
2b8e0 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
2b8f0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
2b900 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2b910 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
2b920 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
2b930 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2b940 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
2b950 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
2b960 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
2b970 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
2b980 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
2b990 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
2b9a0 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
2b9b0 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
2b9c0 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
2b9d0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2b9e0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
2b9f0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
2ba00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
2ba10 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
2ba20 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
2ba30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
2ba40 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
2ba50 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
2ba60 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
2ba70 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
2ba80 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
2ba90 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
2baa0 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
2bab0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
2bac0 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
2bad0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2bae0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2baf0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
2bb00 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
2bb10 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
2bb20 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
2bb30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2bb40 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
2bb50 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
2bb60 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
2bb70 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2bb80 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
2bb90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bba0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2bbb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2bbc0 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47  ns true for [BEG
2bbd0 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45  IN] since.** [BE
2bbe0 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73  GIN] merely sets
2bbf0 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c   internal flags,
2bc00 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c   but the [BEGIN|
2bc10 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d  BEGIN IMMEDIATE]
2bc20 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42   and.** [BEGIN|B
2bc30 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20  EGIN EXCLUSIVE] 
2bc40 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63  commands do touc
2bc50 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  h the database a
2bc60 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nd so.** sqlite3
2bc70 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2bc80 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66   returns false f
2bc90 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64  or those command
2bca0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
2bcb0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d   int sqlite3_stm
2bcc0 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
2bcd0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2bce0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bcf0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2bd00 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2bd10 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
2bd20 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2bd30 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2bd40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2bd50 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
2bd60 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2bd70 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
2bd80 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2bd90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
2bda0 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
2bdb0 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
2bdc0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2bdd0 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
2bde0 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
2bdf0 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
2be00 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2be10 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
2be20 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
2be30 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
2be40 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2be50 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2be60 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2be70 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2be80 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2be90 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2bea0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2beb0 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2bec0 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2bed0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2bee0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2bef0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2bf00 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2bf10 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2bf20 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2bf30 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2bf40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2bf50 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2bf60 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2bf70 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2bf80 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2bf90 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2bfa0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2bfb0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2bfc0 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2bfd0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2bfe0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2bff0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2c000 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2c010 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2c020 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2c030 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2c040 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2c050 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2c060 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2c070 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53  ction open..*/.S
2c080 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2c090 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2c0a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2c0b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c0c0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
2c0d0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
2c0e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
2c0f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c100 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
2c110 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c120 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
2c130 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
2c140 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
2c150 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
2c160 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
2c170 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
2c180 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
2c190 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
2c1a0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
2c1b0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
2c1c0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
2c1d0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
2c1e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c1f0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
2c200 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
2c210 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
2c220 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
2c230 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
2c240 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c250 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
2c260 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
2c270 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
2c280 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
2c290 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
2c2a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c2b0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
2c2c0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
2c2d0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
2c2e0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
2c2f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c300 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
2c310 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
2c320 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
2c330 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
2c340 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
2c350 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
2c360 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
2c370 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c380 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  alue.  The.** [s
2c390 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
2c3a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  ()] interface ca
2c3b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e  n be used to con
2c3c0 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a  struct a new .**
2c3d0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2c3e0 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  e3_value from an
2c3f0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2c400 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
2c410 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
2c420 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
2c430 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
2c440 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
2c450 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
2c460 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e  held.  An intern
2c470 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
2c480 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
2c490 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2c4a0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
2c4b0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
2c4c0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2c4d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2c4e0 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
2c4f0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2c500 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
2c510 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
2c520 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2c530 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
2c540 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2c550 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
2c560 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
2c570 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
2c580 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
2c590 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
2c5a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
2c5b0 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
2c5c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2c5d0 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
2c5e0 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
2c5f0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2c600 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2c610 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2c620 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c630 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
2c640 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
2c650 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
2c660 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
2c670 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
2c680 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
2c690 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
2c6a0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
2c6b0 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
2c6c0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
2c6d0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
2c6e0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2c6f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2c700 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
2c710 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
2c720 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c730 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c740 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
2c750 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
2c760 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
2c770 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
2c780 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c790 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2c7a0 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
2c7b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c7c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
2c7d0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2c7e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2c7f0 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
2c800 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
2c810 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c820 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
2c830 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2c840 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2c850 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
2c860 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2c870 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
2c880 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2c890 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
2c8a0 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
2c8b0 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
2c8c0 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
2c8d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c8e0 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
2c8f0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
2c900 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
2c910 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c920 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
2c930 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
2c940 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
2c950 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
2c960 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
2c970 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
2c980 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
2c990 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
2c9a0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
2c9b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2c9c0 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
2c9d0 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
2c9e0 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
2c9f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2ca00 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
2ca10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2ca20 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2ca30 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2ca40 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
2ca50 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
2ca60 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
2ca70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
2ca80 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
2ca90 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
2caa0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2cab0 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
2cac0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2cad0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2cae0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2caf0 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
2cb00 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
2cb10 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
2cb20 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2cb30 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
2cb40 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
2cb50 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
2cb60 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
2cb70 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
2cb80 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
2cb90 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
2cba0 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
2cbb0 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
2cbc0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
2cbd0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2cbe0 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
2cbf0 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
2cc00 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
2cc10 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
2cc20 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ing}.** METHOD: 
2cc30 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2cc40 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
2cc50 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
2cc60 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
2cc70 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2cc80 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
2cc90 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
2cca0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
2ccb0 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
2ccc0 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
2ccd0 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
2cce0 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
2ccf0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
2cd00 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
2cd10 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
2cd20 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
2cd30 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
2cd40 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
2cd50 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
2cd60 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
2cd70 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
2cd80 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
2cd90 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
2cda0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
2cdb0 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
2cdc0 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
2cdd0 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
2cde0 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
2cdf0 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
2ce00 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
2ce10 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
2ce20 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
2ce30 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2ce40 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
2ce50 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
2ce60 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2ce70 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2ce80 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
2ce90 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
2cea0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
2ceb0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
2cec0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
2ced0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2cee0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
2cef0 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
2cf00 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
2cf10 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2cf20 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
2cf30 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
2cf40 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
2cf50 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
2cf60 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2cf70 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
2cf80 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
2cf90 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
2cfa0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
2cfb0 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
2cfc0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
2cfd0 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
2cfe0 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
2cff0 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
2d000 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
2d010 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
2d020 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
2d030 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
2d040 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2d050 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2d060 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
2d070 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
2d080 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
2d090 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
2d0a0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
2d0b0 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
2d0c0 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
2d0d0 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
2d0e0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
2d0f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
2d100 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2d110 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
2d120 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
2d130 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2d140 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
2d150 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
2d160 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2d170 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
2d180 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2d190 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d1a0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2d1b0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2d1c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2d1d0 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c  _blob() is a NUL
2d1e0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
2d1f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2d200 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65  ter.** is ignore
2d210 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65  d and the end re
2d220 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65  sult is the same
2d230 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   as sqlite3_bind
2d240 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  _null()..**.** ^
2d250 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
2d260 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
2d270 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
2d280 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
2d290 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
2d2a0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
2d2b0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
2d2c0 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
2d2d0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2d2e0 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
2d2f0 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
2d300 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2d310 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
2d320 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
2d330 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2d340 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2d350 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2d360 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e  text16().** is n
2d370 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
2d380 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2d390 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
2d3a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d3b0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
2d3c0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2d3d0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
2d3e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2d3f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2d400 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c  b() is negative,
2d410 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68   then.** the beh
2d420 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2d430 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  ed..** If a non-
2d440 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
2d450 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
2d460 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
2d470 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
2d480 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2d490 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69  text16() or sqli
2d4a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2d4b0 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70  ) then.** that p
2d4c0 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2d4d0 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
2d4e0 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55  .** where the NU
2d4f0 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
2d500 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e  ld occur assumin
2d510 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72  g the string wer
2d520 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61  e NUL.** termina
2d530 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
2d540 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
2d550 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74  r at byte offset
2d560 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20  s less than .** 
2d570 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2d580 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2d590 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  r then the resul
2d5a0 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75  ting string valu
2d5b0 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69  e will.** contai
2d5c0 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e  n embedded NULs.
2d5d0 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20    The result of 
2d5e0 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f  expressions invo
2d5f0 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a  lving strings.**
2d600 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
2d610 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
2d620 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
2d630 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
2d640 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69  he BLOB and stri
2d650 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72  ng binding inter
2d660 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65  faces.** is a de
2d670 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
2d680 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2d690 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
2d6a0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
2d6b0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2d6c0 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
2d6d0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
2d6e0 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
2d6f0 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
2d700 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2d710 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49  call to bind API
2d720 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74   fails..** ^If t
2d730 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2d740 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
2d750 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
2d760 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
2d770 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
2d780 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
2d790 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
2d7a0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
2d7b0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
2d7c0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
2d7d0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
2d7e0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
2d7f0 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
2d800 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
2d810 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
2d820 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
2d830 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
2d840 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
2d850 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
2d860 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2d870 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2d880 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  s..**.** ^The si
2d890 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
2d8a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d8b0 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e  t64() must be on
2d8c0 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  e of.** [SQLITE_
2d8d0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
2d8e0 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  TF16], [SQLITE_U
2d8f0 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
2d900 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20  ITE_UTF16LE].** 
2d910 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65  to specify the e
2d920 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74  ncoding of the t
2d930 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64  ext in the third
2d940 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a   parameter.  If.
2d950 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67  ** the sixth arg
2d960 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2d970 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69  _bind_text64() i
2d980 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
2d990 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75  .** allowed valu
2d9a0 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20  es shown above, 
2d9b0 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65  or if the text e
2d9c0 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
2d9d0 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  rent.** from the
2d9e0 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
2d9f0 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68  ied by the sixth
2da00 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
2da10 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2da20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2da30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2da40 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2da50 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
2da60 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
2da70 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
2da80 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
2da90 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
2daa0 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
2dab0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
2dac0 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
2dad0 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
2dae0 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
2daf0 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
2db00 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
2db10 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
2db20 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
2db30 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
2db40 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
2db50 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
2db60 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2db70 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
2db80 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
2db90 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
2dba0 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
2dbb0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
2dbc0 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
2dbd0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2dbe0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
2dbf0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
2dc00 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2dc10 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
2dc20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2dc30 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
2dc40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2dc50 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
2dc60 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
2dc70 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
2dc80 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
2dc90 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
2dca0 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
2dcb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2dcc0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
2dcd0 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
2dce0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2dcf0 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
2dd00 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
2dd10 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
2dd20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dd30 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
2dd40 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
2dd50 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
2dd60 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2dd70 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
2dd80 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
2dd90 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
2dda0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
2ddb0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
2ddc0 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
2ddd0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
2dde0 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
2ddf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2de00 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
2de10 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2de20 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2de30 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
2de40 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
2de50 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2de60 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47   ^[SQLITE_TOOBIG
2de70 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2de80 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20  ned if the size 
2de90 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  of a string or B
2dea0 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c  LOB.** exceeds l
2deb0 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79  imits imposed by
2dec0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2ded0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  ([SQLITE_LIMIT_L
2dee0 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53  ENGTH]) or.** [S
2def0 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
2df00 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  ]..** ^[SQLITE_R
2df10 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
2df20 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
2df30 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
2df40 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
2df50 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
2df60 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
2df70 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
2df80 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2df90 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2dfa0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
2dfb0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2dfc0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2dfd0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2dfe0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2dff0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2e000 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2e010 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
2e020 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2e030 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2e040 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
2e050 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
2e060 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2e070 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  d_blob64(sqlite3
2e080 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2e090 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  st void*, sqlite
2e0a0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2e0b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e0c0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2e0d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e0e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
2e0f0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2e100 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
2e110 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e120 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2e130 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2e140 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c  , int, int);.SQL
2e150 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2e160 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
2e170 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e180 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
2e190 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e1a0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
2e1b0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
2e1c0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
2e1d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2e1e0 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
2e1f0 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73  3_stmt*,int,cons
2e200 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64  t char*,int,void
2e210 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
2e220 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2e230 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2e240 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e250 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2e260 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2e270 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2e280 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2e290 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  nd_text64(sqlite
2e2a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2e2b0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
2e2c0 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2e2d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e2e0 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
2e2f0 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
2e300 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c  r encoding);.SQL
2e310 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2e320 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
2e330 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e340 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
2e350 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2e360 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2e370 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
2e380 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e390 74 2c 20 69 6e 74 20 6e 29 3b 0a 53 51 4c 49 54  t, int n);.SQLIT
2e3a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2e3b0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36  3_bind_zeroblob6
2e3c0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2e3d0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69   int, sqlite3_ui
2e3e0 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
2e3f0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2e400 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2e410 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2e420 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2e430 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2e440 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2e450 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2e460 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2e470 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2e480 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2e490 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2e4a0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
2e4b0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
2e4c0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
2e4d0 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
2e4e0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
2e4f0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2e500 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
2e510 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e520 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
2e530 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2e540 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
2e550 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
2e560 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
2e570 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
2e580 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
2e590 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
2e5a0 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
2e5b0 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
2e5c0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
2e5d0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
2e5e0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2e5f0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
2e600 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
2e610 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
2e620 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
2e630 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
2e640 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
2e650 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e660 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e670 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2e680 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2e690 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e6a0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
2e6b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e6c0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2e6d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2e6e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e6f0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2e700 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2e710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e720 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
2e730 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45   Parameter.** ME
2e740 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2e750 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2e760 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e770 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
2e780 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2e790 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
2e7a0 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
2e7b0 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2e7c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e7d0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
2e7e0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2e7f0 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
2e800 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2e810 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2e820 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
2e830 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
2e840 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2e850 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2e860 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
2e870 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
2e880 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
2e890 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
2e8a0 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
2e8b0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
2e8c0 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
2e8d0 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
2e8e0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2e8f0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
2e900 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
2e910 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
2e920 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
2e930 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
2e940 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
2e950 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
2e960 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
2e970 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
2e980 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
2e990 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
2e9a0 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
2e9b0 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
2e9c0 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
2e9d0 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
2e9e0 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
2e9f0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
2ea00 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2ea10 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
2ea20 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
2ea30 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
2ea40 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
2ea50 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
2ea60 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
2ea70 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
2ea80 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
2ea90 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2eaa0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2eab0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2eac0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2ead0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2eae0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2eaf0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2eb00 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2eb10 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2eb20 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2eb30 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2eb40 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2eb50 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2eb60 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2eb70 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2eb80 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2eb90 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2eba0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2ebb0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2ebc0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2ebd0 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
2ebe0 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
2ebf0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
2ec00 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
2ec10 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
2ec20 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
2ec30 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
2ec40 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
2ec50 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
2ec60 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2ec70 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
2ec80 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
2ec90 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
2eca0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
2ecb0 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
2ecc0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
2ecd0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
2ece0 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
2ecf0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
2ed00 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
2ed10 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
2ed20 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
2ed30 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2ed40 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2ed50 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2ed60 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2ed70 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2ed80 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ed90 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2eda0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2edb0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2edc0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2edd0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2ede0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2edf0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
2ee00 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2ee10 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
2ee20 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
2ee30 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
2ee40 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2ee50 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2ee60 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2ee70 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
2ee80 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
2ee90 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
2eea0 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
2eeb0 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
2eec0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2eed0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
2eee0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2eef0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
2ef00 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
2ef10 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
2ef20 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
2ef30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2ef40 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
2ef50 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
2ef60 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2ef70 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2ef80 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
2ef90 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
2efa0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2efb0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
2efc0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
2efd0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2efe0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
2eff0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
2f000 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f010 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
2f020 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
2f030 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
2f040 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
2f050 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
2f060 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
2f070 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
2f080 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2f090 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
2f0a0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
2f0b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2f0c0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
2f0d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2f0e0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2f0f0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
2f100 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
2f110 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2f120 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f130 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2f140 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2f150 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
2f160 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
2f170 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
2f180 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2f190 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
2f1a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2f1b0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
2f1c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2f1d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2f1e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2f1f0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
2f200 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2f210 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
2f220 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2f230 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2f240 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
2f250 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
2f260 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2f270 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f280 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
2f290 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
2f2a0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2f2b0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2f2c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2f2d0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
2f2e0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2f2f0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
2f300 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
2f310 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
2f320 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
2f330 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
2f340 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f350 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
2f360 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
2f370 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2f380 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2f390 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2f3a0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2f3b0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2f3c0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2f3d0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2f3e0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2f3f0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
2f400 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
2f410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2f420 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
2f430 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
2f440 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
2f450 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
2f460 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
2f470 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
2f480 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
2f490 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
2f4a0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
2f4b0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
2f4c0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
2f4d0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
2f4e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2f4f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2f500 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
2f510 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
2f520 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2f530 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
2f540 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
2f550 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
2f560 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
2f570 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
2f580 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
2f590 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2f5a0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
2f5b0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
2f5c0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
2f5d0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
2f5e0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
2f5f0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2f600 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2f610 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
2f620 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2f630 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2f640 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f650 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
2f660 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2f670 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
2f680 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
2f690 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
2f6a0 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
2f6b0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2f6c0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2f6d0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2f6e0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2f6f0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2f700 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2f710 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2f720 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2f730 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2f740 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2f750 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2f760 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2f770 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2f780 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2f790 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2f7a0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2f7b0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2f7c0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2f7d0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2f7e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2f7f0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2f800 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2f810 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2f820 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2f830 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2f840 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2f850 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2f860 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2f870 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2f880 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2f890 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f8a0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2f8b0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2f8c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2f8d0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2f8e0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2f8f0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2f900 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2f910 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2f920 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2f930 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2f940 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2f950 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2f960 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2f970 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2f980 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2f990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2f9a0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2f9b0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2f9c0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2f9d0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2f9e0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2f9f0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2fa00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2fa10 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2fa20 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2fa30 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2fa40 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2fa50 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2fa60 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2fa70 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2fa80 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2fa90 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2faa0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2fab0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2fac0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2fad0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2fae0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2faf0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2fb00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2fb10 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2fb20 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2fb30 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2fb40 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2fb50 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2fb60 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2fb70 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2fb80 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2fb90 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2fba0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2fbb0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2fbc0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2fbd0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2fbe0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2fbf0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2fc00 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2fc10 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2fc20 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2fc30 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2fc40 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2fc50 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2fc60 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2fc70 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2fc80 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2fc90 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2fca0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2fcb0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2fcc0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2fcd0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2fce0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2fcf0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2fd00 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2fd10 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2fd20 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2fd30 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2fd40 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2fd50 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2fd60 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2fd70 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2fd80 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2fd90 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2fda0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2fdb0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2fdc0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2fdd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
2fde0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
2fdf0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2fe00 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
2fe10 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2fe20 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2fe30 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2fe40 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
2fe50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2fe60 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
2fe70 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
2fe80 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
2fe90 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
2fea0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2feb0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
2fec0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
2fed0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2fee0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2fef0 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
2ff00 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2ff10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2ff20 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
2ff30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2ff40 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2ff50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2ff60 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2ff70 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2ff80 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2ff90 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2ffa0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ffb0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
2ffc0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2ffd0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2ffe0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2fff0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
30000 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
30010 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
30020 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
30030 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
30040 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
30050 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
30060 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
30070 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
30080 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
30090 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
300a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
300b0 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
300c0 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
300d0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
300e0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
300f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
30100 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
30110 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
30120 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
30130 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
30140 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
30150 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
30160 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
30170 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
30180 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
30190 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
301a0 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
301b0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
301c0 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
301d0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
301e0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
301f0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
30200 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
30210 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
30220 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
30230 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
30240 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
30250 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
30260 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
30270 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
30280 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
30290 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
302a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
302b0 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
302c0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
302d0 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
302e0 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
302f0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
30300 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
30310 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
30320 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
30330 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
30340 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
30350 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
30360 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
30370 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
30380 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
30390 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
303a0 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
303b0 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
303c0 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
303d0 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
303e0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
303f0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
30400 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
30410 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
30420 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
30430 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
30440 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
30450 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
30460 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
30470 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
30480 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
30490 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
304a0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
304b0 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
304c0 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
304d0 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
304e0 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
304f0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
30500 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
30510 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
30520 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
30530 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
30540 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49   values..*/.SQLI
30550 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
30560 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
30570 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
30580 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
30590 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
305a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
305b0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
305c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
305d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
305e0 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
305f0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
30600 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
30610 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74  3_stmt.**.** Aft
30620 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
30630 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
30640 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
30650 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
30660 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
30670 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
30680 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
30690 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
306a0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
306b0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
306c0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
306d0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
306e0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
306f0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
30700 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
30710 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
30720 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
30730 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
30740 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
30750 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
30760 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
30770 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
30780 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
30790 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
307a0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
307b0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
307c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
307d0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
307e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
307f0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
30800 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
30810 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
30820 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
30830 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30840 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
30850 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
30860 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
30870 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
30880 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
30890 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
308a0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
308b0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
308c0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
308d0 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
308e0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
308f0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
30900 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
30910 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
30920 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
30930 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
30940 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
30950 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
30960 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
30970 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
30980 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
30990 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
309a0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
309b0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
309c0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
309d0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
309e0 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
309f0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
30a00 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
30a10 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
30a20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
30a30 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
30a40 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
30a50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
30a60 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
30a70 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
30a80 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
30a90 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
30aa0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
30ab0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
30ac0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
30ad0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
30ae0 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
30af0 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
30b00 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
30b10 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
30b20 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
30b30 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
30b40 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
30b50 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
30b60 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
30b70 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
30b80 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
30b90 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
30ba0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
30bb0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
30bc0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
30bd0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
30be0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
30bf0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
30c00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
30c10 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
30c20 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
30c30 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
30c40 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
30c50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
30c60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
30c70 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
30c80 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
30c90 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
30ca0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
30cb0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
30cc0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
30cd0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
30ce0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
30cf0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
30d00 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
30d10 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
30d20 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
30d30 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
30d40 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
30d50 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
30d60 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
30d70 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
30d80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
30d90 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
30da0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
30db0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
30dc0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
30dd0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
30de0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
30df0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
30e00 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
30e10 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
30e20 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
30e30 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
30e40 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
30e50 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
30e60 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
30e70 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
30e80 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
30e90 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
30ea0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
30eb0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
30ec0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
30ed0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
30ee0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
30ef0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
30f00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30f10 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
30f20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30f30 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
30f40 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
30f50 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
30f60 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
30f70 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
30f80 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
30f90 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
30fa0 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
30fb0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
30fc0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
30fd0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
30fe0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
30ff0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
31000 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31010 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
31020 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
31030 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
31040 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
31050 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
31060 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
31070 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
31080 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
31090 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
310a0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
310b0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
310c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
310d0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
310e0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
310f0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
31100 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
31110 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
31120 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
31130 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
31140 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
31150 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
31160 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
31170 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
31180 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
31190 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
311a0 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
311b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
311c0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
311d0 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
311e0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
311f0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
31200 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
31210 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
31220 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
31230 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31240 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
31250 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
31260 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
31270 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
31280 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
31290 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e  [version 3.6.23.
312a0 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  1] ([dateof:3.6.
312b0 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65  23.1],.** sqlite
312c0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
312d0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
312e0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
312f0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
31300 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
31310 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
31320 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
31330 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
31340 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
31350 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
31360 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
31370 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
31380 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
31390 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
313a0 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
313b0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
313c0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
313d0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
313e0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
313f0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
31400 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
31410 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
31420 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
31430 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
31440 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
31450 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
31460 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
31470 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
31480 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
31490 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
314a0 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
314b0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
314c0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
314d0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
314e0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
314f0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
31500 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
31510 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
31520 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31530 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
31540 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
31550 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
31560 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
31570 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
31580 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
31590 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
315a0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
315b0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
315c0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
315d0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
315e0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
315f0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
31600 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
31610 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
31620 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
31630 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
31640 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
31650 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
31660 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
31670 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
31680 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
31690 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
316a0 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
316b0 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
316c0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
316d0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
316e0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
316f0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
31700 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
31710 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
31720 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
31730 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
31740 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
31750 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
31760 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31770 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
31780 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
31790 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
317a0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
317b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
317c0 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
317d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
317e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
317f0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
31800 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
31810 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
31820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31830 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
31840 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31850 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
31860 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
31870 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
31880 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
31890 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
318a0 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
318b0 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
318c0 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
318d0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
318e0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
318f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31900 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
31910 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
31920 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
31930 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
31940 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
31950 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
31960 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
31970 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
31980 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
31990 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
319a0 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
319b0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
319c0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
319d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
319e0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
319f0 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
31a00 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
31a10 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
31a20 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
31a30 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
31a40 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
31a50 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
31a60 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
31a70 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
31a80 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
31a90 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
31aa0 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
31ab0 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
31ac0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
31ad0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
31ae0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
31af0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31b00 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
31b10 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
31b20 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
31b30 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
31b40 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
31b50 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
31b60 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
31b70 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
31b80 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
31b90 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
31ba0 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
31bb0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
31bc0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
31bd0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
31be0 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
31bf0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
31c00 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
31c10 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
31c20 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
31c30 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
31c40 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
31c50 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
31c60 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
31c70 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
31c80 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
31c90 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
31ca0 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
31cb0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
31cc0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
31cd0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
31ce0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
31cf0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
31d00 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
31d10 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
31d20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
31d30 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
31d40 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
31d50 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
31d60 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
31d70 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
31d80 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
31d90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
31da0 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
31db0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
31dc0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
31dd0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
31de0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
31df0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
31e00 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
31e10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
31e20 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
31e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
31e40 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
31e50 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
31e60 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
31e70 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
31e80 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
31e90 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
31ea0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
31eb0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
31ec0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
31ed0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
31ee0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
31ef0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
31f00 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
31f10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
31f20 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
31f30 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
31f40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
31f50 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
31f60 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
31f70 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
31f80 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
31f90 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
31fa0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
31fb0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
31fc0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
31fd0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
31fe0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
31ff0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
32000 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
32010 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
32020 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
32030 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
32040 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
32050 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
32060 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
32070 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
32080 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
32090 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
320a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
320b0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
320c0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
320d0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
320e0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
320f0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
32100 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
32110 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
32120 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
32130 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
32140 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
32150 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
32160 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
32170 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
32180 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
32190 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
321a0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
321b0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
321c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
321d0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
321e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
321f0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
32200 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
32210 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
32220 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
32230 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
32240 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
32250 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
32260 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
32270 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
32280 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
32290 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
322a0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
322b0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
322c0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
322d0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
322e0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
322f0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
32300 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
32310 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
32320 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
32330 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
32340 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
32350 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
32360 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
32370 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
32380 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
32390 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
323a0 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
323b0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
323c0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
323d0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
323e0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
323f0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
32400 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
32410 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
32420 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
32430 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
32440 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
32450 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
32460 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
32470 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
32480 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
32490 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
324a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
324b0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
324c0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
324d0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
324e0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
324f0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
32500 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
32510 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
32520 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
32530 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
32540 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
32550 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
32560 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
32570 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
32580 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
32590 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
325a0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
325b0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
325c0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
325d0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
325e0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
325f0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
32600 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
32610 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
32620 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
32630 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
32640 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
32650 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
32660 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
32670 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
32680 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
32690 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
326a0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
326b0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
326c0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
326d0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
326e0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
326f0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
32700 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
32710 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32720 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
32730 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
32740 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
32750 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
32760 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
32770 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
32780 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
32790 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
327a0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
327b0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
327c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
327d0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
327e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
327f0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
32800 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
32810 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
32820 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
32830 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
32840 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
32850 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
32860 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
32870 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
32880 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
32890 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
328a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
328b0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
328c0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
328d0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
328e0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
328f0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
32900 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
32910 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
32920 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
32930 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
32940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
32950 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
32960 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
32970 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
32980 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
32990 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
329a0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
329b0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
329c0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
329d0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
329e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
329f0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
32a00 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
32a10 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
32a20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32a30 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
32a40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32a50 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
32a60 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
32a70 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
32a80 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
32a90 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
32aa0 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
32ab0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
32ac0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32ad0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
32ae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32af0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
32b00 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
32b10 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
32b20 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
32b30 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
32b40 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
32b50 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
32b60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
32b70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
32b80 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
32b90 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
32ba0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
32bb0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
32bc0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
32bd0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
32be0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
32bf0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
32c00 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
32c10 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
32c20 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62  * <b>Warning:</b
32c30 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  > ^The object re
32c40 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
32c50 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
32c60 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
32c70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
32c80 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
32c90 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61   In a multithrea
32ca0 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c  ded environment,
32cb0 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  .** an unprotect
32cc0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32cd0 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79   object may only
32ce0 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20   be used safely 
32cf0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
32d00 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
32d10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
32d20 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
32d30 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
32d40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32d50 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
32d60 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
32d70 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
32d80 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
32d90 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
32da0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
32db0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
32dc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
32dd0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
32de0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
32df0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
32e00 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
32e10 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f  e behavior is no
32e20 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a  t threadsafe..**
32e30 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32e40 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
32e50 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
32e60 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
32e70 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
32e80 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
32e90 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
32ea0 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
32eb0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
32ec0 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
32ed0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
32ee0 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
32ef0 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
32f00 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
32f10 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
32f20 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
32f30 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
32f40 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
32f50 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
32f60 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
32f70 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
32f80 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
32f90 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
32fa0 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
32fb0 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
32fc0 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
32fd0 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
32fe0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
32ff0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
33000 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
33010 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
33020 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
33030 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
33040 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
33050 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
33060 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
33070 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
33080 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
33090 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
330a0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
330b0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
330c0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
330d0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
330e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
330f0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
33100 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
33110 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
33120 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
33130 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
33140 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
33150 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
33160 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
33170 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
33180 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
33190 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
331a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
331b0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
331c0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
331d0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  R.** <tr><td>  F
331e0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
331f0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
33200 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
33210 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
33220 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
33230 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
33240 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a   [CAST] to BLOB.
33250 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
33260 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
33270 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
33280 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
33290 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
332a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
332b0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
332c0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
332d0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
332e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
332f0 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
33300 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
33310 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
33320 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
33330 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
33340 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
33350 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
33360 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
33370 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
33380 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
33390 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
333a0 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
333b0 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
333c0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
333d0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
333e0 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
333f0 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
33400 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
33410 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
33420 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
33430 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
33440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
33450 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
33460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33470 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
33480 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
33490 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
334a0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
334b0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
334c0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
334d0 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
334e0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
334f0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
33500 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
33510 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
33520 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
33530 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
33540 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
33550 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
33560 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
33570 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
33580 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
33590 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
335a0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
335b0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
335c0 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
335d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
335e0 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
335f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33600 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
33610 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
33620 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
33630 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
33640 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
33650 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
33660 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
33670 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
33680 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
33690 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
336a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
336b0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
336c0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
336d0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
336e0 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
336f0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
33700 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
33710 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
33720 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
33730 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
33740 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
33750 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
33760 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
33770 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
33780 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
33790 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
337a0 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
337b0 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
337c0 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
337d0 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
337e0 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
337f0 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
33800 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
33810 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
33820 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
33830 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
33840 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
33850 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
33860 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
33870 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
33880 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73  safest policy is
33890 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
338a0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
338b0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
338c0 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
338d0 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
338e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
338f0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
33900 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33910 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
33920 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
33930 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
33940 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
33950 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
33960 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
33970 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33980 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
33990 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
339a0 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
339b0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
339c0 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
339d0 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
339e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
339f0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
33a00 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
33a10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33a20 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
33a30 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
33a40 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
33a50 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
33a60 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
33a70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
33a80 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
33a90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
33aa0 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
33ab0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
33ac0 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
33ad0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
33ae0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
33af0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33b00 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
33b10 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
33b20 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
33b30 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
33b40 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
33b50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33b60 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
33b70 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
33b80 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
33b90 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
33ba0 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
33bb0 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
33bc0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
33bd0 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
33be0 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
33bf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
33c00 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
33c10 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
33c20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
33c30 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
33c40 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
33c50 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
33c60 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
33c70 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
33c80 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d  tically.  Do <em
33c90 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74  >not</em> pass t
33ca0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
33cb0 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
33cc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33cd0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
33ce0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
33cf0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
33d00 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
33d10 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
33d20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
33d30 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
33d40 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
33d50 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
33d60 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
33d70 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
33d80 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
33d90 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
33da0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
33db0 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
33dc0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
33dd0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
33de0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
33df0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
33e00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
33e10 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
33e20 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
33e30 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54  MEM].)^.*/.SQLIT
33e40 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
33e50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
33e60 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
33e70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
33e80 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
33e90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33ea0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
33eb0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
33ec0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
33ed0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33ee0 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
33ef0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
33f00 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20  LITE_API double 
33f10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
33f20 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
33f30 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
33f40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
33f50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
33f60 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
33f70 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
33f80 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
33f90 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
33fa0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
33fb0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
33fc0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
33fd0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
33fe0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
33ff0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
34000 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
34010 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
34020 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
34030 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
34040 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
34050 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
34060 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34070 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
34080 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
34090 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
340a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
340b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
340c0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
340d0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
340e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
340f0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
34100 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
34110 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ect.** DESTRUCTO
34120 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
34130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34140 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
34150 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
34160 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
34170 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34180 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
34190 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
341a0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
341b0 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
341c0 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
341d0 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
341e0 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
341f0 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
34200 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
34210 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
34220 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
34230 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
34240 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
34250 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
34260 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
34270 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
34280 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
34290 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
342a0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
342b0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
342c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
342d0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
342e0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
342f0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
34300 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
34310 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
34320 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34330 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
34340 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
34350 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
34360 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
34370 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
34380 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
34390 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
343a0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
343b0 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
343c0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
343d0 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
343e0 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
343f0 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
34400 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
34410 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34420 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
34430 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
34440 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
34450 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
34460 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
34470 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
34480 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
34490 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
344a0 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
344b0 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
344c0 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
344d0 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
344e0 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
344f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
34500 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
34510 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
34520 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
34530 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
34540 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
34550 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
34560 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
34570 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
34580 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
34590 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
345a0 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
345b0 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ption..*/.SQLITE
345c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
345d0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
345e0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
345f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34600 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
34610 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
34620 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ct.** METHOD: sq
34630 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
34640 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
34650 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
34660 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
34670 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
34680 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
34690 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
346a0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
346b0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
346c0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
346d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
346e0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
346f0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
34700 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
34710 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
34720 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
34730 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
34740 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
34750 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
34760 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
34770 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
34780 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
34790 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
347a0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
347b0 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
347c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
347d0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
347e0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
347f0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
34800 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
34810 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
34820 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
34830 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
34840 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34850 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
34860 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
34870 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
34880 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
34890 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
348a0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
348b0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
348c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
348d0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
348e0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
348f0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
34900 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
34910 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
34920 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
34930 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
34940 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
34950 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
34960 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
34970 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
34980 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
34990 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
349a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
349b0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
349c0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
349d0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
349e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
349f0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
34a00 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
34a10 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53  atement] S..*/.S
34a20 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
34a30 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
34a40 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
34a50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34a60 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
34a70 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
34a80 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
34a90 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
34aa0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
34ab0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
34ac0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34ad0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
34ae0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
34af0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34b00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
34b10 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34b20 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  3.**.** ^These f
34b30 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
34b40 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
34b50 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
34b60 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
34b70 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
34b80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
34b90 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
34ba0 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
34bb0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
34bc0 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
34bd0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
34be0 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
34bf0 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
34c00 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
34c10 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
34c20 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
34c30 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
34c40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
34c50 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
34c60 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
34c70 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
34c80 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
34c90 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
34ca0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
34cb0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
34cc0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
34cd0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
34ce0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
34cf0 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
34d00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
34d10 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
34d20 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
34d30 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
34d40 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
34d50 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
34d60 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
34d70 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
34d80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34d90 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
34da0 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
34db0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
34dc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
34dd0 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
34de0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
34df0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
34e00 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
34e10 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
34e20 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
34e30 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
34e40 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
34e50 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
34e60 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
34e70 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
34e80 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
34e90 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
34ea0 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
34eb0 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
34ec0 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
34ed0 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
34ee0 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
34ef0 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
34f00 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
34f10 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
34f20 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
34f30 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
34f40 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
34f50 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
34f60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
34f70 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
34f80 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
34f90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
34fa0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
34fb0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
34fc0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
34fd0 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
34fe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
34ff0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
35000 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
35010 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
35020 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
35030 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
35040 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
35050 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
35060 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
35070 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
35080 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
35090 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
350a0 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
350b0 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
350c0 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
350d0 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
350e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
350f0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
35100 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
35110 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
35120 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
35130 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
35140 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
35150 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
35160 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
35170 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
35180 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68  on should set th
35190 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  is parameter to.
351a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
351b0 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74  LE] if the funct
351c0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
351d0 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b  on invokes .** [
351e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
351f0 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16le()] on an 
35200 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54  input, or [SQLIT
35210 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68  E_UTF16BE] if th
35220 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
35230 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c  ion invokes [sql
35240 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
35250 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6be()] on an inp
35260 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  ut, or.** [SQLIT
35270 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c  E_UTF16] if [sql
35280 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
35290 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72  6()] is used, or
352a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a   [SQLITE_UTF8].*
352b0 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54  * otherwise.  ^T
352c0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
352d0 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
352e0 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
352f0 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64  times using.** d
35300 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72  ifferent preferr
35310 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
35320 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  s, with differen
35330 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
35340 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e  s for.** each en
35350 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e  coding..** ^When
35360 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
35370 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
35380 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
35390 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
353a0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
353b0 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
353c0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
353d0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
353e0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
353f0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
35400 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74  arameter may opt
35410 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20  ionally be ORed 
35420 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54  with [SQLITE_DET
35430 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74  ERMINISTIC].** t
35440 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68  o signal that th
35450 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  e function will 
35460 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
35470 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69  e same result gi
35480 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ven.** the same 
35490 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20  inputs within a 
354a0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
354b0 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20  ment.  Most SQL 
354c0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a  functions are.**
354d0 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
354e0 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72   The built-in [r
354f0 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e  andom()] SQL fun
35500 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d  ction is an exam
35510 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63  ple of a.** func
35520 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74  tion that is not
35530 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
35540 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72   The SQLite quer
35550 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c  y planner is abl
35560 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20  e to.** perform 
35570 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d  additional optim
35580 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65  izations on dete
35590 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69  rministic functi
355a0 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f  ons, so use.** o
355b0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45  f the [SQLITE_DE
355c0 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61  TERMINISTIC] fla
355d0 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  g is recommended
355e0 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e   where possible.
355f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
35600 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
35610 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
35620 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
35630 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
35640 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
35650 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
35660 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
35670 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
35680 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
35690 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
356a0 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
356b0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
356c0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
356d0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
356e0 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
356f0 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
35700 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
35710 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
35720 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
35730 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
35740 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
35750 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
35760 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
35770 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
35780 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
35790 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
357a0 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
357b0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
357c0 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
357d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
357e0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
357f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
35800 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
35810 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
35820 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
35830 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
35840 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
35850 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
35860 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
35870 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
35880 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
35890 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
358a0 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
358b0 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
358c0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
358d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
358e0 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
358f0 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
35900 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
35910 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
35920 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
35930 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
35940 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
35950 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
35960 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
35970 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
35980 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
35990 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
359a0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
359b0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
359c0 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
359d0 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
359e0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
359f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35a00 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
35a10 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
35a20 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
35a30 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
35a40 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
35a50 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
35a60 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
35a70 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
35a80 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
35a90 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
35aa0 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
35ab0 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
35ac0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
35ad0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
35ae0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
35af0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
35b00 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
35b10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35b20 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
35b30 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
35b40 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
35b50 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
35b60 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
35b70 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
35b80 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
35b90 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
35ba0 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
35bb0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
35bc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
35bd0 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
35be0 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
35bf0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
35c00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
35c10 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
35c20 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
35c30 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
35c40 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
35c50 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
35c60 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
35c70 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
35c80 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
35c90 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
35ca0 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
35cb0 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
35cc0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
35cd0 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
35ce0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
35cf0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
35d00 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
35d10 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
35d20 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
35d30 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
35d40 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
35d50 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
35d60 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
35d70 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
35d80 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
35d90 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
35da0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
35db0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
35dc0 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
35dd0 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
35de0 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
35df0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
35e00 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
35e10 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
35e20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35e30 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
35e40 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
35e50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35e60 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
35e70 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
35e80 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
35e90 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
35ea0 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
35eb0 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
35ec0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35ed0 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
35ee0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
35ef0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
35f00 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
35f10 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
35f20 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
35f30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
35f40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
35f50 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
35f60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
35f70 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
35f80 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
35f90 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
35fa0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
35fb0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
35fc0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
35fd0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
35fe0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
35ff0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
36000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
36010 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
36020 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
36030 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
36040 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
36050 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
36060 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
36070 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
36080 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
36090 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
360a0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
360b0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
360c0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
360d0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
360e0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
360f0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
36100 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36110 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
36120 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
36130 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
36140 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49  ontext*).);.SQLI
36150 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36160 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36170 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
36180 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
36190 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
361a0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
361b0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
361c0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
361d0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
361e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
361f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
36200 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
36210 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
36220 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
36230 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
36240 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
36250 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
36260 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
36270 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
36280 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
36290 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
362a0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
362b0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
362c0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
362d0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
362e0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
362f0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
36300 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
36310 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
36320 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20          1    /* 
36330 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35  IMP: R-37514-355
36340 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  66 */.#define SQ
36350 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
36360 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a      2    /* IMP:
36370 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a   R-03371-37637 *
36380 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36390 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
363a0 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35  3    /* IMP: R-5
363b0 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64  1971-34154 */.#d
363c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
363d0 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
363e0 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
363f0 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
36400 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
36410 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
36420 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f  /* Deprecated */
36430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36440 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
36450 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
36460 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
36470 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
36480 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
36490 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68  n Flags.**.** Th
364a0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ese constants ma
364b0 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68  y be ORed togeth
364c0 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  er with the .** 
364d0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70  [SQLITE_UTF8 | p
364e0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
364f0 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66  coding] as the f
36500 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
36510 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
36520 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
36530 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
36540 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
36550 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
36560 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
36570 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  v2()]..*/.#defin
36580 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49  e SQLITE_DETERMI
36590 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a  NISTIC    0x800.
365a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
365b0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
365c0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
365d0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
365e0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
365f0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
36600 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
36610 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
36620 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
36630 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
36640 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
36650 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
36660 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
36670 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
36680 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
36690 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
366a0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
366b0 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65  s.  To encourage
366c0 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20   programmers to 
366d0 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66  avoid.** these f
366e0 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c  unctions, we wil
366f0 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68  l not explain wh
36700 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
36710 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
36720 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
36730 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
36740 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
36750 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
36760 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
36770 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
36780 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
36790 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
367a0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
367b0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
367c0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
367d0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
367e0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
367f0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
36800 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
36810 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
36820 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
36830 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
36840 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
36850 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
36860 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
36870 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
36880 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
36890 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
368a0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
368b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
368c0 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
368d0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
368e0 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20  int64,int),.    
368f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36900 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f    void*,sqlite3_
36910 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
36920 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36930 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61  Obtaining SQL Va
36940 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
36950 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
36960 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
36970 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
36980 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
36990 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
369a0 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
369b0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
369c0 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
369d0 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
369e0 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
369f0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
36a00 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a  gregate.  .**.**
36a10 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
36a20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
36a30 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
36a40 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
36a50 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
36a60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36a70 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
36a80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36a90 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
36aa0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
36ab0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
36ac0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
36ad0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
36ae0 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
36af0 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
36b00 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
36b10 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
36b20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
36b30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
36b40 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
36b50 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
36b60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
36b70 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
36b80 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
36b90 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
36ba0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
36bb0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
36bc0 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
36bd0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
36be0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
36bf0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
36c00 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
36c10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
36c20 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
36c30 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
36c40 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
36c50 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
36c60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
36c70 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
36c80 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
36c90 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
36ca0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
36cb0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
36cc0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
36cd0 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
36ce0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
36cf0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
36d00 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
36d10 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
36d20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
36d30 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
36d40 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
36d50 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
36d60 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
36d70 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
36d80 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
36d90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
36da0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
36db0 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
36dc0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
36dd0 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
36de0 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
36df0 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
36e00 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
36e10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
36e20 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
36e30 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
36e40 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
36e50 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
36e60 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
36e70 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
36e80 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
36e90 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
36ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
36eb0 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
36ec0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
36ed0 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
36ee0 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
36ef0 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
36f00 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
36f10 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
36f20 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
36f30 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
36f40 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
36f50 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
36f60 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
36f70 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
36f80 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
36f90 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
36fa0 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
36fb0 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
36fc0 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
36fd0 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
36fe0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
36ff0 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
37000 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
37010 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
37020 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
37030 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
37040 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
37050 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
37060 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
37070 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
37080 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
37090 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
370a0 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
370b0 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
370c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
370d0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
370e0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
370f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
37100 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
37110 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
37120 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
37130 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
37140 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
37150 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
37160 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
37170 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37180 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
37190 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
371a0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
371b0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
371c0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
371d0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
371e0 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
371f0 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
37200 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
37210 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
37220 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ers..*/.SQLITE_A
37230 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
37240 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
37250 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
37260 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
37270 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
37280 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
37290 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
372a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
372b0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
372c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
372d0 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73  ITE_API double s
372e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
372f0 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
37300 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
37310 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
37320 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
37330 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
37340 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
37350 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
37360 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
37370 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
37380 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
37390 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
373a0 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
373b0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
373c0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
373d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
373e0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
373f0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
37400 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
37410 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
37420 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
37430 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
37440 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
37450 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
37460 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
37470 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
37480 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
37490 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
374a0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
374b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
374c0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
374d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
374e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
374f0 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53  F: Finding The S
37500 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61  ubtype Of SQL Va
37510 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
37520 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
37530 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
37540 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29  value_subtype(V)
37550 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
37560 73 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f  s the subtype fo
37570 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61  r.** an [applica
37580 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
37590 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d   function] argum
375a0 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 74  ent V.  The subt
375b0 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ype.** informati
375c0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
375d0 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64  o pass a limited
375e0 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
375f0 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53  xt from.** one S
37600 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61  QL function to a
37610 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 65  nother.  Use the
37620 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
37630 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72  _subtype()].** r
37640 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68  outine to set th
37650 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 68  e subtype for th
37660 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
37670 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  f an SQL functio
37680 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
37690 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20  makes no use of 
376a0 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20  subtype itself. 
376b0 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65   It merely passe
376c0 73 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a  s the subtype.**
376d0 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74   from the result
376e0 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61   of one [applica
376f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
37700 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20   function] into 
37710 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20  the.** input of 
37720 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 53 51 4c 49  another..*/.SQLI
37730 54 45 5f 41 50 49 20 75 6e 73 69 67 6e 65 64 20  TE_API unsigned 
37740 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
37750 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65  e_subtype(sqlite
37760 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
37770 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79  * CAPI3REF: Copy
37780 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61   And Free SQL Va
37790 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
377a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
377b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
377c0 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e  _value_dup(V) in
377d0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
377e0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
377f0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
37800 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75  bject D and retu
37810 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
37820 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68   that copy.  ^Th
37830 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
37840 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  ] returned.** is
37850 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   a [protected sq
37860 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
37870 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20  ect even if the 
37880 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a  input is not..**
37890 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
378a0 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
378b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
378c0 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f  L if V is NULL o
378d0 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79  r if a.** memory
378e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
378f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
37900 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
37910 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72  (V) interface fr
37920 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  ees an [sqlite3_
37930 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
37940 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
37950 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
37960 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e  e3_value_dup()].
37970 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c    ^If V is a NUL
37980 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  L pointer.** the
37990 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  n sqlite3_value_
379a0 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72  free(V) is a har
379b0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
379c0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
379d0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
379e0 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73  3_value_dup(cons
379f0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
37a00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
37a10 69 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  id sqlite3_value
37a20 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61  _free(sqlite3_va
37a30 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
37a40 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
37a50 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
37a60 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54  n Context.** MET
37a70 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
37a80 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
37a90 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67  mentations of ag
37aa0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
37ab0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a  tions use this.*
37ac0 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  * routine to all
37ad0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72  ocate memory for
37ae0 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
37af0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tate..**.** ^The
37b00 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
37b10 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37b20 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
37b30 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
37b40 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69   .** for a parti
37b50 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20  cular aggregate 
37b60 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
37b70 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20  .** allocates N 
37b80 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
37b90 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72  s out that memor
37ba0 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
37bb0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
37bc0 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e  he new memory. ^
37bd0 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
37be0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
37bf0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
37c00 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
37c10 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
37c20 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
37c30 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68   instance,.** th
37c40 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
37c50 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69   returned.  Sqli
37c60 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37c70 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61  ntext() is norma
37c80 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  lly.** called on
37c90 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f  ce for each invo
37ca0 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53  cation of the xS
37cb0 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64  tep callback and
37cc0 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73   then one.** las
37cd0 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  t time when the 
37ce0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
37cf0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57  is invoked.  ^(W
37d00 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63  hen no rows matc
37d10 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74  h.** an aggregat
37d20 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74  e query, the xSt
37d30 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ep() callback of
37d40 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
37d50 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  unction.** imple
37d60 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76  mentation is nev
37d70 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46  er called and xF
37d80 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64  inal() is called
37d90 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a   exactly once..*
37da0 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73  * In those cases
37db0 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  , sqlite3_aggreg
37dc0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69  ate_context() mi
37dd0 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f  ght be called fo
37de0 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  r the.** first t
37df0 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ime from within 
37e00 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a  xFinal().)^.**.*
37e10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61  * ^The sqlite3_a
37e20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37e30 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65  (C,N) routine re
37e40 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
37e50 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69  nter .** when fi
37e60 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20  rst called if N 
37e70 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  is less than or 
37e80 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
37e90 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20   if a memory.** 
37ea0 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
37eb0 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
37ec0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
37ed0 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
37ee0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37ef0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
37f00 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
37f10 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
37f20 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
37f30 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
37f40 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
37f50 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
37f60 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
37f70 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
37f80 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
37f90 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
37fa0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
37fb0 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
37fc0 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
37fd0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
37fe0 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68  on.)^  Within th
37ff0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
38000 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61  k, it is customa
38010 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30  ry to set.** N=0
38020 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c   in calls to sql
38030 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
38040 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74  ontext(C,N) so t
38050 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74  hat no .** point
38060 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  less memory allo
38070 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a  cations occur..*
38080 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
38090 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
380a0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
380b0 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
380c0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
380d0 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
380e0 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
380f0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
38100 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
38110 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
38120 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
38130 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
38140 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
38150 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
38160 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
38170 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
38180 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
38190 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
381a0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
381b0 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
381c0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
381d0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
381e0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
381f0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
38200 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
38210 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
38220 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
38230 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
38240 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
38250 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
38260 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
38270 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
38280 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38290 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
382a0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
382b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
382c0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ntext.**.** ^The
382d0 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
382e0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
382f0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
38300 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
38310 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
38320 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
38330 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
38340 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
38350 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
38360 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
38370 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
38380 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
38390 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
383a0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
383b0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
383c0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
383d0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
383e0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
383f0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
38400 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
38410 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
38420 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
38430 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
38440 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
38450 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
38460 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
38470 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
38480 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38490 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
384a0 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
384b0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
384c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
384d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
384e0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
384f0 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
38500 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
38510 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
38520 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
38530 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
38540 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
38550 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
38560 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
38570 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
38580 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
38590 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
385a0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
385b0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
385c0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
385d0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
385e0 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ction..*/.SQLITE
385f0 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71  _API sqlite3 *sq
38600 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
38610 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
38620 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
38630 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
38640 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
38650 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ata.** METHOD: s
38660 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
38670 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
38680 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
38690 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
386a0 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
386b0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
386c0 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
386d0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
386e0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
386f0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
38700 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
38710 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
38720 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
38730 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
38740 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
38750 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
38760 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
38770 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
38780 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
38790 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
387a0 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68   where this migh
387b0 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69  t be useful is i
387c0 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  n